No description
- C 41.9%
- Python 35.1%
- C++ 16.1%
- Makefile 4.4%
- Shell 2.5%
|
|
||
|---|---|---|
| docs | ||
| fw | ||
| mech | ||
| pcb | ||
| .gitignore | ||
| .gitmodules | ||
| CLAUDE.md | ||
| README.md | ||
Framework expansion card: USB 2 hub + LoRa
KiCad 10 project in pcb/, firmware in fw/ (see fw/README.md), datasheets in docs/.
- USB-C plug (P1) → CH335F hub (U3) → two USB-C receptacles (J2, J3), each switched by a CH217A (U5, U4)
- Hub port 3 → CH32X035F8U6 MCU (U2)
- RA-01SH LoRa module (U11, SX1262), two XL-4020 WS2812-type LEDs (D1, D3)
- AP2112K-3.3 LDO (U12) supplies hub, MCU and radio
Firmware notes
MCU pin map (U2, QFN-20)
| Pin | Port | Net | Use |
|---|---|---|---|
| 2 | PA0 | LORA_RST | GPIO out |
| 3 | PA1 | LORA_DIO1 | GPIO in / EXTI1 |
| 4 | PA2 | LED_DIN | TIM2_CH3 + DMA (WS2812) |
| 5 | PA3 | I2C_SDA | bit-banged EEPROM slave (emulated open-drain) |
| 6–9 | PA4–PA7 | LORA_NSS/SCK/MISO/MOSI | SPI1 default pins |
| 10 | PB0 | LORA_BUSY | GPIO in |
| 11 | PB1 | BOOT | button to GND, internal pull-up |
| 13 | PB11 | HUB_RESET | hub RESET#, drive low or release (input) |
| 14 | PC18 | SWDIO | TP1 |
| 16 | PC19 | SWCLK | TP3 (GND on TP2) |
| 17/18 | PC16/PC17 | CH32_D−/D+ | USB device on hub port 3 |
| 19 | PC14 | USB_CC | plug CC line (USB PD CC1), R1 5.1k pull-down |
| 20 | PC15 | I2C_SCL | bit-banged EEPROM slave (input) |
| 12, 15 | PB3, PB12 | – | unused, set as pull-up inputs |
The QFN-20 has no reset pin; reset is power-on only.
Bootloader
- Uses the ch32fun custom bootloader, not the WCH ROM bootloader (the ROM one is entered by PC17/D+ high at power-up).
- Entry button SW1 shorts PB1 to GND. There is no external pull-up: the bootloader must enable the PB1 internal pull-up (12–65 µA) before reading the pin.
- Recovery path if the flash is broken: SWD on TP1 (SWDIO), TP3 (SWCLK), TP2 (GND). There is no 3.3 V pad, so the card has to be plugged in while debugging.
- BOOT shares EXTI line 1 with LORA_DIO1 (PA1): poll the button, don't use its interrupt.
Hub configuration (emulated I2C EEPROM)
The hub reads a 24C02-style EEPROM at address 0 on LED3/SCL and LED4/SDA while it comes out of reset (CH334/335 datasheet §3.4, §3.5). The MCU pretends to be that EEPROM.
- No hardware I2C on these pins. PA3/PC15 have no I2C function, so the slave is bit-banged.
- Clock is 187.5 kHz and the hub drives SCL push-pull, so no clock stretching. One bit is 5.33 µs, clock-low ≈ 2.67 µs ≈ 128 cycles at 48 MHz.
- Use polling, not interrupts. Hold the hub in reset, disable interrupts, release HUB_RESET and run a tight loop from RAM (flash has 3 wait states at 48 MHz) until STOP or timeout. Nothing else needs servicing: the MCU's own USB goes through the hub.
- The CH32X035 has no open-drain GPIO mode (RM: outputs are push-pull or alternate push-pull; only the I2C peripheral pins are open-drain). Emulate it: keep the output latch at 0, switch the pin to output to pull low and to input to release. ch32fun's
GPIO_CFGLR_OUT_*_ODmodes drive high on this chip. - SDA: only drive low. The hub has ~250 µA internal pull-up on SDA. No external pull-ups on the board.
- After configuration the pins become the hub's LED3/LED4 outputs: leave PA3/PC15 as inputs.
- HUB_RESET: drive low or release (switch to input). Driving RESET# high during power-up enables CDP charging mode and disables hub low-power sleep (§3.2.2). Reset pulse > 4 µs; RESET# has an internal ~25k pull-up.
- EEPROM content (bytes 00h–0Ah, rest 0xFF unless strings are used):
- 04h CHKSUM must equal VID_L + VID_H + PID_L + PID_H + 1, otherwise the hub ignores all of it.
- 0Ah CFG: bit0 GANG_MODE = 0 (individual over-current; matches R14 pulling PGANG low), bit5 OC_LEVEL = 0 (otherwise the floating OVCUR3#/OVCUR4# report over-current).
- 06h Device Removable: bit3 = 1 (MCU on port 3 is not removable).
- 07h Port Number: 3 to hide the unused port 4 (optional).
- To verify on hardware: whether a RESET# pulse (not only power-up) re-reads the EEPROM, and the SCL duty cycle.
Port mapping
Net names for ports 1 and 2 are crossed, the wiring is consistent:
| Hub port | Data | ESD | Connector | Power switch | Hub pins |
|---|---|---|---|---|---|
| 1 | DM1/DP1 | U8 | J2 | U5 | PWREN1# (4), OVCUR1# (24) |
| 2 | DM2/DP2 | U7 | J3 | U4 | PWREN2# (2), OVCUR2# (23) |
| 3 | DM3/DP3 | – | U2 MCU | – | – |
Downstream current limit: R15/R16 56k → ~1.07 A per port.
USB PD / CC
- PC14 is wired to the plug's CC line with R1 (5.1k) as the sink pull-down. Keep the CC internal pull-ups off.
- Set
USBPD_PHY_V33 = 1(AFIO) for 3.3 V supply.USB_PHY_V33defaults to 1.
LoRa (RA-01SH / SX1262)
SetDio2AsRfSwitchCtrl(true): DIO2 drives the module's RF switch; TXEN/RXEN are not connected.- No TCXO (passive crystal): do not call
SetDio3AsTcxoCtrl; in RadioLib usetcxoVoltage = 0. - NSS and NRESET have internal pull-ups in the SX1262. Antenna via the module's IPEX connector.
LEDs
- 2 LEDs chained: PA2 → R17 470R → D1 → D3 (
NR_LEDS = 2). D1 is on the top side, D3 on the bottom. - Powered from VBUS (5 V); 3.3 V data is enough (VIH = 0.5·VDD).