docs: clean up and expand badge link docs

docs/api/badge_link.rst

+.. _Badge Link API:
+
 ``badge_link`` module
 =====================
 
+.. note::
+
+   See also: :ref:`Badge link overview<Badge link>`
+
 .. automodule:: badge_link
    :members:
    :undoc-members:

docs/badge/badge_link.rst

@@ -3,91 +3,77 @@
 Badge Link
 ==========
 
-Badge Link is a protocol for digital communication over the 3.5mm ports.
-
-You can configure individual pins (tip, ring) of each of the two 3.5mm ports
-(line in, line out) to be used as TX or RX for UART, at any baud rate up to
-5mbit in theory. In practice lower baud rates are recommended to avoid data
-corruption.
-
-MIDI can be used by configuring the baud rate to 31250. There is no galvanic
-isolation, but there are current limiting resistors.
-
-The input protection can handle between +5v and -3v.
+.. note::
 
-Example usage
--------------
+   See also: :ref:`Micropython API docs<Badge link api>`
 
-On both badges:
+Badge Link is a protocol for digital communication over the 3.5mm jacks.
 
-.. code-block:: python
+You can configure individual pins (tip, ring) of each of the two 3.5mm jacks
+(line in, line out) to be used as anything a GPIO of the ESP32S3 can do with
+the following limitations:
 
-   import badge_link
-   from machine import UART
-   badge_link.enable(badge_link.PIN_MASK_ALL)
+ * The input protection can handle between -2V and +3.3V **or** ±10mA max.
 
-On badge 1, connect the cable to line out, and configure uart with tx on tip
-(as an example)
+   * This means that within that voltage range, you can source or sink higher
+     currents
+   * And higher voltages will be clamped to a safe range if the external source
+     doesn't exceed the current limits
 
-.. code-block:: python
+ * The GPIOs have a 100 Ohm resistor in series which limits current output and
+   may limit bandwidth depending on cable capacity
+ * There is no galvanic isolation (as commonly used in MIDI devices). Ground
+   loops can introduce noise in the audio input/output.
 
-   uart = UART(
-       1,
-       baudrate=115200,
-       tx=badge_link.PIN_INDEX_LINE_OUT_TIP,
-       rx=badge_link.PIN_INDEX_LINE_OUT_RING
-   )
+Typical use cases include:
 
-On badge 2, connect the cable to line in, and configure uart with tx on ring:
+ * :ref:`badge-link-uart`
+ * :ref:`badge-link-midi`
+ * :ref:`badge-link-eurorack-cv`
 
-.. code-block:: python
 
-   uart = UART(
-       1,
-       baudrate=115200,
-       tx=badge_link.PIN_INDEX_LINE_IN_RING,
-       rx=badge_link.PIN_INDEX_LINE_IN_TIP
-   )
+.. _badge-link-uart:
 
-Then write and read from each side:
+UART
+----
 
-.. code-block:: python
+UART can be used with any baud rate up to 5mbit, in theory. In practice lower
+baud rates are recommended to avoid data corruption. Longer cables do not
+necessarily mean lower baud rates (higher cable capacity)
 
-   uart.write("hiiii")
-   uart.read(5)
+.. _badge-link-midi:
 
 MIDI
 ----
 
-You can do raw midi with this.
+MIDI is unidirectional UART with a baud rate of 31250, with one pin acting as
+the "current source" (Vcc, an always high GPIO) and one pin acting as the
+"current sink" (data, UART tx or rx). Sleeve can be assumed to be always ground.
 
-.. note::
-   Good reference for midi commands:
-   https://computermusicresource.com/MIDI.Commands.html
+There are three competing arrangements for this:
+
+ * MIDI Type A: Tip is sink/data, ring is source/Vcc.
+ * MIDI Type B: Ring is sink/data, tip is source/Vcc.
+ * TS / Non-TRS / Type C: Like type B, but ring and sleeve are shorted.
+
+See https://minimidi.world/ for more details.
 
-.. code-block:: python
+Type A has been adopted as the standard by the MIDI Manufacturers
+Association in 2018, but there are many type B devices too.
 
-   import badge_link
-   from machine import UART
-   uart = UART(
-       1,
-       baudrate=31250,
-       tx=badge_link.PIN_INDEX_LINE_OUT_TIP,
-       rx=badge_link.PIN_INDEX_LINE_OUT_RING
-   )
+On our side, it is up to the application developer to decide how to configure
+the pins.
 
-   # note on channel 1, note #60, velocity 127
-   uart.write(bytes([144, 60, 127]))
+.. _badge-link-eurorack-cv:
 
-   # note off channel 1, note #60
-   uart.write(bytes([144, 60, 127]))
+Eurorack control voltages
+-------------------------
 
-Turn this into usb midi with a cheap adapter or https://github.com/rppicomidi/midi2usbdev
+.. warning::
 
-Read incoming events from linux:
+   We haven't tested this.
 
-.. code-block:: bash
+It's theoretically possible to use the ADC and PWM (LEDC) peripherals of the
+ESP32-S3 to interact with eurorack control voltages.
 
-   aseqdump -l
-   # use the port below
-   aseqdump -p 20:0
+The PWM output will likely need an RC filter to output a smoother signal.

python_payload/mypystubs/badge_link.pyi

 """
-Badgelink API.
-
-Badgelink allows for multiple flow3r badges to connect together over the TRRS
+Badge Link allows for multiple flow3r badges to connect together over the TRS
 jacks and exchange data. It also allows for flow3r badges to access the outside
 world over the same connector, even if that world is outside of the realm of
 usual audio frequencies. Think: eurorack control voltages, MIDI, ...
@@ -26,8 +24,10 @@ True
 >>> badge_link.right.active()
 True
 >>> badge_link.right.tip
+JackPin(right tip)
+>>> badge_link.right.tip.pin
 Pin(4)
->>> rt = badge_link.right.tip
+>>> rt = badge_link.right.tip.pin
 >>> rt.init(mode=machine.Pin.OUT)
 >>> rt.on()
 """