[realtek-ambz] Improve flashing guide, add test pads for WR2 board (#147

) * platform/realtek-ambz: Improve flashing guide Known USB adapter compatibility issues. Emphasize, so that the paragraph is easier to notice. Signed-off-by: Pavel Fedin <[email protected]> * base/wr2: Add UART2 test pads to the WR2 diagram The module has UART2, necessary for flashing, only on test pads. Document this. Signed-off-by: Pavel Fedin <[email protected]> * Move test pads to separate files, update variants * Update wiring guide --------- Signed-off-by: Pavel Fedin <[email protected]> Co-authored-by: Kuba Szczodrzyński <[email protected]>
libretiny-eu · Jul 11, 2023 · 6169f68 · 6169f68
1 parent f8876bb
commit 6169f68
Show file tree

Hide file tree

Showing 11 changed files with 182 additions and 25 deletions.
diff --git a/boards/_base/pcb/wr2-test.json b/boards/_base/pcb/wr2-test.json
@@ -0,0 +1,44 @@
+{
+	"pcb": {
+		"back": [
+			{
+				"comment": "RXD Pad",
+				"name": "test_pad_1mm",
+				"pos": "5.4,14.5"
+			},
+			{
+				"comment": "TXD Pad",
+				"name": "test_pad_1mm",
+				"pos": "5.4,13.2"
+			},
+			{
+				"comment": "RXD Pad label",
+				"id": "rxd",
+				"name": "label_line_up",
+				"pos": "4.6,14.6",
+				"vars": {
+					"DIR": "left",
+					"RASTER": 2,
+					"W": 2.1,
+					"H": 0
+				}
+			},
+			{
+				"comment": "TXD Pad label",
+				"id": "txd",
+				"name": "label_line_up",
+				"pos": "5.4,12.4",
+				"vars": {
+					"DIR": "left",
+					"RASTER": 2,
+					"W": 2.7,
+					"H": 0.5
+				}
+			}
+		],
+		"test_pads": {
+			"TRX2": "wr2.back.rxd.anchor",
+			"TTX2": "wr2.back.txd.anchor"
+		}
+	}
+}
diff --git a/boards/_base/pcb/wr2.json b/boards/_base/pcb/wr2.json
@@ -43,6 +43,14 @@
 			"11": {
 				"IC": 14,
 				"ARD": "D7"
+			},
+			"TTX2": {
+				"IC": 1,
+				"ARD": "D8"
+			},
+			"TRX2": {
+				"IC": 2,
+				"ARD": "D9"
 			}
 		}
 	}

diff --git a/boards/_base/pcb/wr2e-test.json b/boards/_base/pcb/wr2e-test.json
@@ -0,0 +1,44 @@
+{
+	"pcb": {
+		"back": [
+			{
+				"comment": "RXD Pad",
+				"name": "test_pad_1mm",
+				"pos": "5.4,14.5"
+			},
+			{
+				"comment": "TXD Pad",
+				"name": "test_pad_1mm",
+				"pos": "5.4,13.2"
+			},
+			{
+				"comment": "RXD Pad label",
+				"id": "rxd",
+				"name": "label_line_up",
+				"pos": "4.6,14.6",
+				"vars": {
+					"DIR": "left",
+					"RASTER": 2,
+					"W": 2.1,
+					"H": 0
+				}
+			},
+			{
+				"comment": "TXD Pad label",
+				"id": "txd",
+				"name": "label_line_up",
+				"pos": "5.4,12.4",
+				"vars": {
+					"DIR": "left",
+					"RASTER": 2,
+					"W": 2.7,
+					"H": 0.5
+				}
+			}
+		],
+		"test_pads": {
+			"TRX2": "wr2e.back.rxd.anchor",
+			"TTX2": "wr2e.back.txd.anchor"
+		}
+	}
+}
diff --git a/boards/_base/pcb/wr2e.json b/boards/_base/pcb/wr2e.json
@@ -46,6 +46,14 @@
 			"11": {
 				"IC": 14,
 				"ARD": "D6"
+			},
+			"TTX2": {
+				"IC": 1,
+				"ARD": "D7"
+			},
+			"TRX2": {
+				"IC": 2,
+				"ARD": "D8"
 			}
 		}
 	}

diff --git a/boards/variants/wr2.c b/boards/variants/wr2.c
@@ -22,6 +22,10 @@ PinInfo lt_arduino_pin_info_list[PINS_COUNT] = {
 	{PA_14, PIN_GPIO | PIN_IRQ | PIN_PWM | PIN_SWD,                      PIN_NONE, 0},
 	// D7: PA15, PWM1, SWDIO
 	{PA_15, PIN_GPIO | PIN_IRQ | PIN_PWM | PIN_SWD,                      PIN_NONE, 0},
+	// D8: PA30, UART2_TX, I2C0_SDA, PWM4
+	{PA_30, PIN_GPIO | PIN_IRQ | PIN_PWM | PIN_I2C | PIN_UART,           PIN_NONE, 0},
+	// D9: PA29, UART2_RX, I2C0_SCL, PWM4
+	{PA_29, PIN_GPIO | PIN_IRQ | PIN_PWM | PIN_I2C | PIN_UART,           PIN_NONE, 0},
 	// A1: ADC2
 	{AD_2,  PIN_ADC,                                                     PIN_NONE, 0},
 };
@@ -34,6 +38,8 @@ PinInfo *lt_arduino_pin_gpio_map[] = {
 	[15] = &(lt_arduino_pin_info_list[6]), // PA_15 (D7)
 	[18] = &(lt_arduino_pin_info_list[3]), // PA_18 (D4)
 	[23] = &(lt_arduino_pin_info_list[4]), // PA_23 (D5)
-	[41] = &(lt_arduino_pin_info_list[7]), // AD_2 (A1)
+	[29] = &(lt_arduino_pin_info_list[8]), // PA_29 (D9)
+	[30] = &(lt_arduino_pin_info_list[7]), // PA_30 (D8)
+	[41] = &(lt_arduino_pin_info_list[9]), // AD_2 (A1)
 };
 // clang-format on
diff --git a/boards/variants/wr2.h b/boards/variants/wr2.h
@@ -6,21 +6,25 @@
 
 // Pins
 // ----
-#define PINS_COUNT         8  // Total GPIO count
-#define NUM_DIGITAL_PINS   7  // Digital inputs/outputs
+#define PINS_COUNT         10 // Total GPIO count
+#define NUM_DIGITAL_PINS   9  // Digital inputs/outputs
 #define NUM_ANALOG_INPUTS  1  // ADC inputs
-#define NUM_ANALOG_OUTPUTS 6  // PWM & DAC outputs
+#define NUM_ANALOG_OUTPUTS 8  // PWM & DAC outputs
 #define PINS_GPIO_MAX      41 // Last usable GPIO number
 
 // Wire Interfaces
 // ---------------
+#define PIN_WIRE0_SCL 29u // PA_29
+#define PIN_WIRE0_SDA 30u // PA_30
 #define PIN_WIRE1_SCL 18u // PA_18
 #define PIN_WIRE1_SDA 23u // PA_23
 
 // Serial ports
 // ------------
 #define PIN_SERIAL0_RX 18u // PA_18
 #define PIN_SERIAL0_TX 23u // PA_23
+#define PIN_SERIAL2_RX 29u // PA_29
+#define PIN_SERIAL2_TX 30u // PA_30
 
 // Pin function macros
 // -------------------
@@ -34,24 +38,32 @@
 #define PIN_PA15  15u // PA_15
 #define PIN_PA18  18u // PA_18
 #define PIN_PA23  23u // PA_23
+#define PIN_PA29  29u // PA_29
+#define PIN_PA30  30u // PA_30
 #define PIN_PWM0  14u // PA_14
 #define PIN_PWM1  15u // PA_15
 #define PIN_PWM2  0u  // PA_0
 #define PIN_PWM3  12u // PA_12
-#define PIN_PWM4  5u  // PA_5
+#define PIN_PWM4  29u // PA_29
 #define PIN_RX0   18u // PA_18
+#define PIN_RX2   29u // PA_29
 #define PIN_SCK0  18u // PA_18
 #define PIN_SCK1  18u // PA_18
+#define PIN_SCL0  29u // PA_29
 #define PIN_SCL1  18u // PA_18
+#define PIN_SDA0  30u // PA_30
 #define PIN_SDA1  23u // PA_23
 #define PIN_TX0   23u // PA_23
+#define PIN_TX2   30u // PA_30
 
 // Port availability
 // -----------------
 #define HAS_SERIAL0             1
+#define HAS_SERIAL2             1
+#define HAS_WIRE0               1
 #define HAS_WIRE1               1
-#define SERIAL_INTERFACES_COUNT 1
-#define WIRE_INTERFACES_COUNT   1
+#define SERIAL_INTERFACES_COUNT 2
+#define WIRE_INTERFACES_COUNT   2
 
 // Arduino pin names
 // -----------------
@@ -62,6 +74,8 @@
 #define PIN_D5 23u // PA_23
 #define PIN_D6 14u // PA_14
 #define PIN_D7 15u // PA_15
+#define PIN_D8 30u // PA_30
+#define PIN_D9 29u // PA_29
 #define PIN_A1 41u // AD_2
 
 // Static pin names
@@ -74,3 +88,5 @@ static const unsigned char D4 = PIN_D4;
 static const unsigned char D5 = PIN_D5;
 static const unsigned char D6 = PIN_D6;
 static const unsigned char D7 = PIN_D7;
+static const unsigned char D8 = PIN_D8;
+static const unsigned char D9 = PIN_D9;
diff --git a/boards/variants/wr2e.c b/boards/variants/wr2e.c
@@ -22,6 +22,10 @@ PinInfo lt_arduino_pin_info_list[PINS_COUNT] = {
 	{PA_14, PIN_GPIO | PIN_IRQ | PIN_PWM | PIN_SWD,                                PIN_NONE, 0},
 	// D6: PA15, PWM1, SWDIO
 	{PA_15, PIN_GPIO | PIN_IRQ | PIN_PWM | PIN_SWD,                                PIN_NONE, 0},
+	// D7: PA30, UART2_TX, I2C0_SDA, PWM4
+	{PA_30, PIN_GPIO | PIN_IRQ | PIN_PWM | PIN_I2C | PIN_UART,                     PIN_NONE, 0},
+	// D8: PA29, UART2_RX, I2C0_SCL, PWM4
+	{PA_29, PIN_GPIO | PIN_IRQ | PIN_PWM | PIN_I2C | PIN_UART,                     PIN_NONE, 0},
 	// A1: ADC2
 	{AD_2,  PIN_ADC,                                                               PIN_NONE, 0},
 };
@@ -34,6 +38,8 @@ PinInfo *lt_arduino_pin_gpio_map[] = {
 	[18] = &(lt_arduino_pin_info_list[3]), // PA_18 (D3)
 	[19] = &(lt_arduino_pin_info_list[1]), // PA_19 (D1)
 	[23] = &(lt_arduino_pin_info_list[4]), // PA_23 (D4)
-	[41] = &(lt_arduino_pin_info_list[7]), // AD_2 (A1)
+	[29] = &(lt_arduino_pin_info_list[8]), // PA_29 (D8)
+	[30] = &(lt_arduino_pin_info_list[7]), // PA_30 (D7)
+	[41] = &(lt_arduino_pin_info_list[9]), // AD_2 (A1)
 };
 // clang-format on
diff --git a/boards/variants/wr2e.h b/boards/variants/wr2e.h
@@ -6,22 +6,27 @@
 
 // Pins
 // ----
-#define PINS_COUNT         8  // Total GPIO count
-#define NUM_DIGITAL_PINS   7  // Digital inputs/outputs
+#define PINS_COUNT         10 // Total GPIO count
+#define NUM_DIGITAL_PINS   9  // Digital inputs/outputs
 #define NUM_ANALOG_INPUTS  2  // ADC inputs
-#define NUM_ANALOG_OUTPUTS 5  // PWM & DAC outputs
+#define NUM_ANALOG_OUTPUTS 7  // PWM & DAC outputs
 #define PINS_GPIO_MAX      41 // Last usable GPIO number
 
 // Wire Interfaces
 // ---------------
-#define PIN_WIRE1_SCL 18u // PA_18
-#define PIN_WIRE1_SDA 23u // PA_23
+#define PIN_WIRE0_SCL   29u // PA_29
+#define PIN_WIRE0_SDA_0 19u // PA_19
+#define PIN_WIRE0_SDA_1 30u // PA_30
+#define PIN_WIRE1_SCL   18u // PA_18
+#define PIN_WIRE1_SDA   23u // PA_23
 
 // Serial ports
 // ------------
 #define PIN_SERIAL0_CTS 19u // PA_19
 #define PIN_SERIAL0_RX  18u // PA_18
 #define PIN_SERIAL0_TX  23u // PA_23
+#define PIN_SERIAL2_RX  29u // PA_29
+#define PIN_SERIAL2_TX  30u // PA_30
 
 // Pin function macros
 // -------------------
@@ -39,24 +44,31 @@
 #define PIN_PA18  18u // PA_18
 #define PIN_PA19  19u // PA_19
 #define PIN_PA23  23u // PA_23
+#define PIN_PA29  29u // PA_29
+#define PIN_PA30  30u // PA_30
 #define PIN_PWM0  14u // PA_14
 #define PIN_PWM1  15u // PA_15
 #define PIN_PWM3  12u // PA_12
-#define PIN_PWM4  5u  // PA_5
+#define PIN_PWM4  29u // PA_29
 #define PIN_RX0   18u // PA_18
+#define PIN_RX2   29u // PA_29
 #define PIN_SCK0  18u // PA_18
 #define PIN_SCK1  18u // PA_18
+#define PIN_SCL0  29u // PA_29
 #define PIN_SCL1  18u // PA_18
-#define PIN_SDA0  19u // PA_19
+#define PIN_SDA0  30u // PA_30
 #define PIN_SDA1  23u // PA_23
 #define PIN_TX0   23u // PA_23
+#define PIN_TX2   30u // PA_30
 
 // Port availability
 // -----------------
 #define HAS_SERIAL0             1
+#define HAS_SERIAL2             1
+#define HAS_WIRE0               1
 #define HAS_WIRE1               1
-#define SERIAL_INTERFACES_COUNT 1
-#define WIRE_INTERFACES_COUNT   1
+#define SERIAL_INTERFACES_COUNT 2
+#define WIRE_INTERFACES_COUNT   2
 
 // Arduino pin names
 // -----------------
@@ -67,6 +79,8 @@
 #define PIN_D4 23u // PA_23
 #define PIN_D5 14u // PA_14
 #define PIN_D6 15u // PA_15
+#define PIN_D7 30u // PA_30
+#define PIN_D8 29u // PA_29
 #define PIN_A0 19u // PA_19
 #define PIN_A1 41u // AD_2
 
@@ -81,3 +95,5 @@ static const unsigned char D3 = PIN_D3;
 static const unsigned char D4 = PIN_D4;
 static const unsigned char D5 = PIN_D5;
 static const unsigned char D6 = PIN_D6;
+static const unsigned char D7 = PIN_D7;
+static const unsigned char D8 = PIN_D8;
diff --git a/boards/wr2.json b/boards/wr2.json
@@ -4,7 +4,8 @@
 		"realtek-ambz-2mb-788k",
 		"ic/rtl8710bn",
 		"pcb/wr2-base",
-		"pcb/wr2"
+		"pcb/wr2",
+		"pcb/wr2-test"
 	],
 	"build": {
 		"mcu": "rtl8710bn",

diff --git a/boards/wr2e.json b/boards/wr2e.json
@@ -4,7 +4,8 @@
 		"realtek-ambz-2mb-788k",
 		"ic/rtl8710bn",
 		"pcb/wr2-base",
-		"pcb/wr2e"
+		"pcb/wr2e",
+		"pcb/wr2e-test"
 	],
 	"build": {
 		"mcu": "rtl8710bn",

diff --git a/docs/platform/realtek-ambz/flashing.md b/docs/platform/realtek-ambz/flashing.md
@@ -5,7 +5,12 @@
 [Read chip docs](README.md){ .md-button }
 </div>
 
-Downloading is done using UART2 (sometimes called Log_UART). Refer to your board documentation to find the correct pins. You need a good USB<->UART adapter (preferably a real FT232RL) for the process.
+Downloading is done using UART2 (sometimes called Log_UART). Refer to your board documentation to find the correct pins.
+
+!!! tip
+    You need a good USB<->UART adapter for the process. Some chips may not support 1.5M baud rate,
+	required by the ROM for the initial handshake. Widespread PL2303 is currently known not to work,
+	at least under Windows. FT232RL is verified to work reliably.
 
 **Read [Using ltchiptool](../../flashing/tools/ltchiptool.md) to learn the flashing procedure**
 
@@ -16,21 +21,23 @@ Downloading is done using UART2 (sometimes called Log_UART). Refer to your board
 	----|------------------------------
 	RX  | TX2 (Log_TX / PA30)
 	TX  | RX2 (Log_RX / PA29)
-	RTS | CEN (or RST, optional)
-	DTR | TX2 (Log_TX / PA30, optional)
 	GND | GND
 
 	Make sure to use a good 3.3V power supply, otherwise the adapter might
 	lose power during chip reset. Usually, the adapter's power regulator
 	is not enough and an external power supply is needed (like AMS1117).
 
-	If you didn't connect RTS and DTR, you need to put the chip in download
-	mode manually. This is done by connecting CEN to GND, while holding TX2 (Log_TX)
-	to GND as well. After doing that, you need to disconnect TX2 from GND.
+	You need to put the chip in download mode manually:
+
+	- connect CEN to GND
+	- connect TX2 to GND
+	- release CEN from GND
+	- release TX2 from GND
 
 	If the download mode is enabled, you'll see a few garbage characters
 	printed to the serial console every second.
 
+
 !!! tip
 	Because the UART uploading code is programmed in the ROM of the chip, it can't be software-bricked, even if you damage the bootloader.