Adding LinkSPI documentation

README.md

@@ -32,7 +32,7 @@ The library uses message queues to send/receive data and transmits when it's pos
 
 ![screenshot](https://user-images.githubusercontent.com/1631752/99154109-1d131980-268c-11eb-86b1-7a728f639e5e.png)
 
-## Constructor options
+## Constructor
 
 `new LinkCable(...)` accepts these **optional** parameters:
 
@@ -55,7 +55,7 @@ Name | Return type | Description
 `isConnected()` | **bool** | Returns `true` if there are at least 2 connected players.
 `playerCount()` | **u8** *(0~4)* | Returns the number of connected players.
 `currentPlayerId()` | **u8** *(0~3)* | Returns the current player id.
-`canRead(playerId)` | **bool** | Returns true if there are pending messages from player #`playerId`.
+`canRead(playerId)` | **bool** | Returns `true` if there are pending messages from player #`playerId`.
 `read(playerId)` | **u16** | Returns one message from player #`playerId`.
 `consume()` | - | Marks the current data as processed, enabling the library to fetch more.
 `send(data)` | - | Sends `data` to all connected players.
@@ -79,8 +79,29 @@ Name | Return type | Description
 `writePin(pin, isHigh)` | - | Sets a `pin` to be high or not (when set as an output).
 `setSIInterrupts(isEnabled)` | - | If it `isEnabled`, a IRQ will be generated when `SI` changes from *HIGH* to *LOW*.
 
-# LinkSPI
+# 🔗 LinkSPI
 
-// TODO: WRITE
+*(aka Normal Mode)*
+
+This is, essentially, SPI mode 3. In this implementation packets are set to 32-bit, as there's no benefit to using the 8-bit version. You can use this to interact with other GBAs or computers that know SPI.
 
 ![screenshot](https://user-images.githubusercontent.com/1631752/213068614-875049f6-bb01-41b6-9e30-98c73cc69b25.png)
+
+## Constructor
+
+`new LinkSPI(...)` requires these parameters:
+
+Name | Type | Description
+--- | --- | ---
+`mode` | **LinkSPI::Mode** | One of `LinkSPI::Mode::SLAVE`, `LinkSPI::Mode::MASTER_256KBPS`, or `LinkSPI::Mode::MASTER_2MBPS`.
+
+## Methods
+
+Name | Return type | Description
+--- | --- | ---
+`isActive()` | **bool** | Returns whether the library is active or not.
+`activate()` | - | Activates the library.
+`deactivate()` | - | Deactivates the library.
+`transfer(data)` | **u32** | Exchanges `data` with the other end. Returns the received data.
+`transfer(data, cancel)` | **u32** | Like `transfer(data)` but accepts a `cancel` function. The library will continuously invoke it, and abort the transfer if it returns `true`.
+`getMode()` | **LinkSPI::Mode** | Returns the current mode.

examples/LinkSPI_basic/src/main.cpp

@@ -18,26 +18,36 @@ void init() {
 int main() {
   init();
 
+  bool firstTransfer = false;
+
   while (true) {
     std::string output = "";
     u16 keys = ~REG_KEYS & KEY_ANY;
 
     if (linkSPI == NULL) {
+      firstTransfer = true;
       output += "START: Set as Master\n";
-      output += "SELECT: Set as Slave";
+      output += "SELECT: Set as Slave\n";
+      output +=
+          "\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n[!] to test this demo...\n      "
+          "...use a GBC Link Cable!";
 
       // (1) Create a LinkSPI instance
-      if (keys & KEY_START)
+      if (keys & KEY_START) {
         linkSPI = new LinkSPI(LinkSPI::Mode::MASTER_256KBPS);
-      if (keys & KEY_SELECT)
+        linkSPI->activate();
+      }
+      if (keys & KEY_SELECT) {
         linkSPI = new LinkSPI(LinkSPI::Mode::SLAVE);
+        linkSPI->activate();
+      }
     } else {
       // Title
       auto modeName =
           linkSPI->getMode() == LinkSPI::Mode::SLAVE ? "Slave" : "Master";
       output += std::string("[") + modeName + "]\n";
       output += "(stop: L+R)\n\n";
-      if (!linkSPI->isActive())
+      if (firstTransfer)
         log(output + "Waiting...");
 
       // Transfer
@@ -47,6 +57,7 @@ int main() {
       });
       output += "local:  " + std::to_string(keys) + "\n";
       output += "remote: " + std::to_string(remoteKeys) + "\n";
+      firstTransfer = false;
 
       // Cancel
       if ((keys & KEY_L) && (keys & KEY_R)) {

lib/LinkSPI.h

@@ -8,10 +8,12 @@
 // - 1) Include this header in your main.cpp file and add:
 //       LinkSPI* linkSPI = new LinkSPI(LinkSPI::Mode::MASTER_256KBPS);
 //       // (use LinkSPI::Mode::SLAVE on the other end)
-// - 2) Exchange 32-bit data with the other end:
+// - 2) Initialize the library with:
+//       linkSPI->activate();
+// - 3) Exchange 32-bit data with the other end:
 //       u32 data = linkGPIO->transfer(0x1234);
 //       // (this blocks the console indefinitely)
-// - 3) Exchange data with a cancellation callback:
+// - 4) Exchange data with a cancellation callback:
 //       u32 data = linkGPIO->transfer(0x1234, []() {
 //         u16 keys = ~REG_KEYS & KEY_ANY;
 //         return keys & KEY_START;
@@ -76,7 +78,7 @@ class LinkSPI {
 
   template <typename F>
   u32 transfer(u32 data, F cancel) {
-    if (!isEnabled || isMaster())
+    if (isEnabled && isMaster())
       activate();
 
     setData(data);