text

doc/uart_notes.md

@@ -1,9 +1,29 @@
-# Various notes about UART and baudrates
+# Notes about UART and baudrates
+<a id="top"></a>
 
 Proxmark3 RDV4 can interact with the client program running on a host via several means, let's go through each of them and study the notion of baudrate.
 
+# Table of Contents
+- [Notes about UART and baudrates](#notes-about-uart-and-baudrates)
+- [Table of Contents](#table-of-contents)
+  - [USB-CDC ACM](#usb-cdc-acm)
+  - [Proxmark3 FPC USART](#proxmark3-fpc-usart)
+  - [Proxmark3 FPC USART + BT add-on (blue shark)](#proxmark3-fpc-usart--bt-add-on-blue-shark)
+    - [BT add-on AT configuration mode](#bt-add-on-at-configuration-mode)
+    - [BT add-on connected mode](#bt-add-on-connected-mode)
+    - [RFCOMM](#rfcomm)
+    - [BT add-on baudrate](#bt-add-on-baudrate)
+    - [BT on host side: internal BT](#bt-on-host-side-internal-bt)
+    - [BT on host side: HC-06 dongle](#bt-on-host-side-hc-06-dongle)
+    - [HC-06 dongle AT configuration mode](#hc-06-dongle-at-configuration-mode)
+  - [Proxmark3 FPC USART + FTDI](#proxmark3-fpc-usart--ftdi)
+  - [BT add-on + FTDI](#bt-add-on--ftdi)
+  - [HC-06 AT Commands](#hc-06-at-commands)
+
+
 
 ## USB-CDC ACM
+^[Top](#top)
 
 USB CDC (Communications Device Class) ACM (Abstract Control Model) is a way to emulate serial ports over USB.
 On the host, it appears as a virtual serial port, e.g. `/dev/ttyACM0`.
@@ -16,6 +36,7 @@ The real communication speed relates only to the USB link and is roughly about 7
 In USB CDC ACM the host could "set" other baudrates and the USB CDC device would be informed of the changes (see `SET_LINE_CODING` and `GET_LINE_CODING`), which is potentially interesting if, behind, it has to configure a real UART, but we're not in this type of setup so baudrate notion on USB CDC (visible e.g. with `stty -F /dev/ttyACM0`) can simply be totally ignored. 
 
 ## Proxmark3 FPC USART
+^[Top](#top)
 
 Proxmark3 RDV4 has a FPC connector outputting on 2 pins a USART from the ARM:
 
@@ -40,8 +61,10 @@ And for things to work fine, both sets have to match!
 Internally, the desired baudrate is converted to UART settings: a BRGR and a FP. The resulting baudrate will be close to but not always equal to the desired baudrate. Serial ports typically have some error tolerance in the actual baudrates. Theoretically < 2.5% on each side (so 5% in total), < 2% to be on the safe side. In the current firmware configuration, the Proxmark3 can provide any baudrate up to 2Mbauds with an error of max 2%, and selected baudrates up to 6Mbauds (tested with a FTDI C232HM DDHSL-0 cable).
 
 ## Proxmark3 FPC USART + BT add-on (blue shark)
+^[Top](#top)
 
 ### BT add-on AT configuration mode
+^[Top](#top)
 
 When the BT add-on is turned on but no actively connected to a host, it's in a configuration mode where it accepts "AT" commands and its blue LED is blinking at about 1Hz.
 
@@ -54,18 +77,21 @@ Some specific commands are available when you add `BTADDON` to `PLATFORM_EXTRAS`
 Manual configuration is also possible with `usart txrx -d "AT+Px"` and `usart txrx -d "AT+BAUDx"`.
 
 ### BT add-on connected mode
+^[Top](#top)
 
 When the BT add-on is paired with a host and the host establishes an active connection, the blue LED turns on steadily.
 
 The add-on acts as a bridge, between its UART and the BT communication channel, here a RFCOMM channel.
 
 ### RFCOMM
+^[Top](#top)
 
 The Bluetooth RFCOMM protocol provides an emulation of serial ports over the L2CAP protocol ([ref](https://www.amd.e-technik.uni-rostock.de/ma/gol/lectures/wirlec/bluetooth_info/rfcomm.html)).
 
 As for USB-CDC, the real speed of the link is unrelated to serial baudrate notion. Literature mentions a maximal value of 360kbps for some implementations, but the HC-06 Bluetooth module within the BT add-on is limited as the vast majority of similar devices to 128kbps.
 
 ### BT add-on baudrate
+^[Top](#top)
 
 Which baudrate will make sense?
 
@@ -78,6 +104,7 @@ Using 115200 is safe and within the 128kbps limit.
 Using 230400 allows to maximize the BT channel capacity, but the gain is limited, about 10-15% faster than 115200. There is also a risk to take into account: you're delivering data too fast to the HC-06 than what it's capable to send over RFCOMM. So you're filling the internal buffer faster than it can be emptied. If you're doing it for too many data, you'll reach a point where data will be lost (once the internal buffer is full), which is observable with `hw status` for higher baudrates at the time of writing (`b17da830edadb8462e02a95a00b4a58302cce71b`).
 
 ### BT on host side: internal BT
+^[Top](#top)
 
 On the other side of the BT link is the host. If it has built-in Bluetooth, the host can present a virtual serial port to the Proxmark3 client.
 E.g. on Linux, `rfcomm` allows to create such bindings of a BT device and a virtual port: `rfcomm bind rfcomm0 20:19:04:20:04:08` will create the virtual port `/dev/rfcomm0`.
@@ -89,6 +116,7 @@ Note that the rfcomm implementation separates pairing from actual connection:
 * when the program closes, the link will be closed and the BT add-on blue LED will blink again, showing that the BT ad-on is in AT configuration mode.
 
 ### BT on host side: HC-06 dongle
+^[Top](#top)
 
 On the other side of the BT link is the host. If it does not have a built-in Bluetooth, the host can use
 * a generic BT add-on, and we're back in the previous case
@@ -111,12 +139,14 @@ The USB-UART speed is selected when a program opens the port. E.g.
 * the Python script meant to configure HC-06 dongle. The baudrate is given as option to `serial.Serial()` when opening `/dev/ttyUSB0`.
 
 ### HC-06 dongle AT configuration mode
+^[Top](#top)
 
 When the BT add-on is turned off, the HC-06 dongle will not be connected and will fall back into its AT configuration mode (its LED is blinking).
 
 `tools/btaddon/hc06_factory.py` changes several times the USB-UART baudrate and parity till it matches the HC-06 dongle settings, then changes the baudrate and parity of the dongle to a default value. (`hc06_factory.py` does more but we're only interested in baudrate in this discussion)
 
 ## Proxmark3 FPC USART + FTDI
+^[Top](#top)
 
 Just for completeness, let's mention the possibility to connect the Proxmark3 to the host via FPC and a USB-UART bridge such as a FTDI cable (or CP2102, ch341, PL2303...).
 It's not very interesting because USB-CDC is faster anyway.
@@ -124,6 +154,7 @@ It's not very interesting because USB-CDC is faster anyway.
 In that case, Proxmark3 USART settings (configured e.g. via `usart config` while connected by USB-CDC) have to match FTDI cable settings, selected by the program opening the serial port (`/dev/ttyUSB0`).
 
 ## BT add-on + FTDI
+^[Top](#top)
 
 Just for completeness, let's mention the possibility to connect the BT add-on to the host via FPC and a USB-UART bridge such as a FTDI cable (or CP2102, ch341, PL2303...).
 The only interest is for debug purposes, e.g. to reconfigure an add-on from the host rather than from the Proxmark3 itself.
@@ -148,6 +179,7 @@ Turn BTpower switch ON, leave Battery switch OFF
 Use e.g. `tools/btaddon/hc06_factory.py` with `role = b'S'`
 
 ## HC-06 AT Commands
+^[Top](#top)
 
 The HC-06 supports a subset of the AT commands and they are listed below. The commands are limited and vary in how to give parameters. A pure informative command like AT+VERSION just returns a string with current firmware the HC-06 has installed.