Merge pull request #20 from afska/v6.3.0

⏱️ LinkUART, 🖱️ LinkPS2Mouse, ⌨️ LinkPS2Keyboard

Author: afska

README.md

@@ -12,6 +12,9 @@ A set of Game Boy Advance (GBA) C++ libraries to interact with the Serial Port.
 - [🌎](#-LinkUniversal) [LinkUniversal.hpp](lib/LinkUniversal.hpp): Add multiplayer support to your game, both with 👾 *Link Cables* and 📻 *Wireless Adapters*, using the **same API**!
 - [🔌](#-LinkGPIO) [LinkGPIO.hpp](lib/LinkGPIO.hpp): Use the Link Port however you want to control **any device** (like LEDs, rumble motors, and that kind of stuff)!
 - [🔗](#-LinkSPI) [LinkSPI.hpp](lib/LinkSPI.hpp): Connect with a PC (like a **Raspberry Pi**) or another GBA (with a GBC Link Cable) using this mode. Transfer up to 2Mbit/s!
+- [⏱️](#%EF%B8%8F-LinkUART) [LinkUART.hpp](lib/LinkUART.hpp): Easily connect to **any PC** using a USB to UART cable!
+- [🖱️](#%EF%B8%8F-LinkPS2Mouse) [LinkPS2Mouse.hpp](lib/LinkPS2Mouse.hpp): Connect a **PS/2 mouse** to the GBA for extended controls!
+- [⌨️](#%EF%B8%8F-LinkPS2Keyboard) [LinkPS2Keyboard.hpp](lib/LinkPS2Keyboard.hpp): Connect a **PS/2 keyboard** to the GBA for extended controls!
 
 *(click on the emojis for documentation)*
 
@@ -87,7 +90,7 @@ Name | Return type | Description
 
 # 💻 LinkCableMultiboot
 
-*(aka Multiboot through Multi-Play mode)*
+*(aka Multiboot through Multi-Play Mode)*
 
 This tool allows sending Multiboot ROMs (small 256KiB programs that fit in EWRAM) from one GBA to up to 3 slaves, using a single cartridge.
 
@@ -343,3 +346,78 @@ The GBA operates using **SPI mode 3** (`CPOL=1, CPHA=1`). Here's a connection di
     </td>
   </tr>
 </table>
+
+# ⏱️ LinkUART
+
+*(aka UART Mode)*
+
+This is the GBA's implementation of UART. You can use this to interact with a PC using a _USB to UART cable_. You can change the buffer size by changing the compile-time constant `LINK_UART_QUEUE_SIZE`.
+
+![photo](https://github.com/afska/gba-link-connection/assets/1631752/2ca8abb8-1a38-40bb-bf7d-bf29a0f880cd)
+
+## Methods
+
+Name | Return type | Description
+--- | --- | ---
+`isActive()` | **bool** | Returns whether the library is active or not.
+`activate(baudRate, dataSize, parity, useCTS)` | - | Activates the library using a specific UART mode. _Defaults: 9600bps, 8-bit data, no parity bit, no CTS_.
+`deactivate()` | - | Deactivates the library.
+`sendLine(string)` | - | Takes a null-terminated `string`, and sends it followed by a `'\n'` character. The null character is not sent.
+`sendLine(data, cancel)` | - | Like `sendLine(string)` but accepts a `cancel()` function. The library will continuously invoke it, and abort the transfer if it returns `true`.
+`readLine(string, [limit])` | **bool** | Reads characters into `string` until finding a `'\n'` character or a character `limit` is reached. A null terminator is added at the end. Returns `false` if the limit has been reached without finding a newline character.
+`readLine(string, cancel, [limit])` | - | Like `readLine(string, [limit])` but accepts a `cancel()` function. The library will continuously invoke it, and abort the transfer if it returns `true`.
+`send(buffer, size, offset)` | - | Sends `size` bytes from `buffer`, starting at byte `offset`.
+`read(buffer, size, offset)` | **u32** | Tries to read `size` bytes into `(u8*)(buffer + offset)`. Returns the number of read bytes. 
+`canRead()` | **bool** | Returns whether there are bytes to read or not.
+`canSend()` | **bool** | Returns whether there is room to send new messages or not.
+`availableForRead()` | **u32** | Returns the number of bytes available for read.
+`availableForSend()` | **u32** | Returns the number of bytes available for send (buffer size - queued bytes).
+`read()` | **u8** | Reads a byte. Returns 0 if nothing is found.
+`send(data)` | - | Sends a `data` byte.
+
+## UART Configuration
+
+The GBA operates using 1 stop bit, but everything else can be configured. By default, the library uses `8N1`, which means 8-bit data and no parity bit. RTS/CTS is disabled by default.
+
+![diagram](https://github.com/afska/gba-link-connection/assets/1631752/a6a58f94-da24-4fd9-9603-9c7c9a493f93)
+
+- Black wire (GND) -> GBA GND.
+- Green wire (TX) -> GBA SI.
+- White wire (RX) -> GBA SO.
+
+# 🖱️ LinkPS2Mouse
+
+A PS/2 mouse driver for the GBA. Use it to add mouse support to your homebrew games.
+
+![photo](https://github.com/afska/gba-link-connection/assets/1631752/6856ff0d-0f06-4a9d-8ded-280052e02b8d)
+
+## Constructor
+
+`new LinkPS2Mouse(timerId)`, where `timerId` is the GBA Timer used for delays.
+
+## Methods
+
+Name | Return type | Description
+--- | --- | ---
+`isActive()` | **bool** | Returns whether the library is active or not.
+`activate()` | - | Activates the library.
+`deactivate()` | - | Deactivates the library.
+`report(data[3])` | - | Fills the `data` int array with a report. The first int contains _clicks_ that you can check against the bitmasks `LINK_PS2_MOUSE_LEFT_CLICK`, `LINK_PS2_MOUSE_MIDDLE_CLICK`, and `LINK_PS2_MOUSE_RIGHT_CLICK`. The second int is the _X movement_, and the third int is the _Y movement_.
+
+# ⌨️ LinkPS2Keyboard
+
+A PS/2 keyboard driver for the GBA. Use it to add keyboard support to your homebrew games.
+
+![photo](https://github.com/afska/gba-link-connection/assets/1631752/4c5fa3ed-5d96-45fe-ad24-73bc3f71c63f)
+
+## Constructor
+
+`new LinkPS2Keyboard(onEvent)`, where `onEvent` is a function pointer that will receive the scan codes (`u8`). You should check a PS/2 scan code list online, but there are some examples included like `LINK_PS2_KEYBOARD_KEY_ENTER` and `LINK_PS2_KEYBOARD_KEY_RELEASE`.
+
+## Methods
+
+Name | Return type | Description
+--- | --- | ---
+`isActive()` | **bool** | Returns whether the library is active or not.
+`activate()` | - | Activates the library.
+`deactivate()` | - | Deactivates the library.

examples/LinkCableMultiboot_demo/src/main.cpp

@@ -49,7 +49,7 @@ int main() {
     // Sender options
     if (isSenderMode) {
       if (result != LinkCableMultiboot::Result::SUCCESS)
-        log("LinkCableMultiboot_demo\n  (v6.2.3)\n\nPress START to send the "
+        log("LinkCableMultiboot_demo\n  (v6.3.0)\n\nPress START to send the "
             "ROM...\nPress B to set client mode...");
 
       if (keys & KEY_START) {

examples/LinkCable_basic/src/main.cpp

@@ -45,7 +45,7 @@ int main() {
     u16 keys = ~REG_KEYS & KEY_ANY;
     linkCable->send(keys + 1);  // (avoid using 0)
 
-    std::string output = "LinkCable_basic (v6.2.3)\n\n";
+    std::string output = "LinkCable_basic (v6.3.0)\n\n";
     if (linkCable->isConnected()) {
       u8 playerCount = linkCable->playerCount();
       u8 currentPlayerId = linkCable->currentPlayerId();

examples/LinkCable_full/src/main.cpp

@@ -93,10 +93,10 @@ inline void setUpInterrupts() {
 
 void printTutorial() {
 #ifndef USE_LINK_UNIVERSAL
-  DEBULOG("LinkCable_full (v6.2.3)");
+  DEBULOG("LinkCable_full (v6.3.0)");
 #endif
 #ifdef USE_LINK_UNIVERSAL
-  DEBULOG("LinkUniversal_full (v6.2.3)");
+  DEBULOG("LinkUniversal_full (v6.3.0)");
 #endif
 
   DEBULOG("");

examples/LinkCable_stress/src/main.cpp

@@ -89,10 +89,10 @@ int main() {
 
   while (true) {
 #ifndef USE_LINK_UNIVERSAL
-    std::string output = "LinkCable_stress (v6.2.3)\n\n";
+    std::string output = "LinkCable_stress (v6.3.0)\n\n";
 #endif
 #ifdef USE_LINK_UNIVERSAL
-    std::string output = "LinkUniversal_stress (v6.2.3)\n\n";
+    std::string output = "LinkUniversal_stress (v6.3.0)\n\n";
 #endif
 
     linkConnection->deactivate();

examples/LinkGPIO_demo/src/main.cpp

@@ -27,7 +27,7 @@ int main() {
 
   while (true) {
     // (3) Use the pins
-    std::string output = "LinkGPIO_demo (v6.2.3)\n\n";
+    std::string output = "LinkGPIO_demo (v6.3.0)\n\n";
 
     // Commands
     u16 keys = ~REG_KEYS & KEY_ANY;