No description
  • C 41.9%
  • Python 35.1%
  • C++ 16.1%
  • Makefile 4.4%
  • Shell 2.5%
Find a file
Nils Schulte f600e5fc9e fw: udev rule for user write access to the red LEDs
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-10 15:37:52 +01:00
docs Add firmware notes and datasheets, MCU decoupling, wider tracks 2026-10-19 14:00:30 +00:00
fw fw: udev rule for user write access to the red LEDs 2026-11-10 15:37:52 +01:00
mech mech: one-piece printable case for the expansion card 2026-11-09 09:01:42 +00:00
pcb Shield bleed resistor, more 0.2 mm tracks, layout fixes 2026-10-19 14:45:41 +00:00
.gitignore mech: one-piece printable case for the expansion card 2026-11-09 09:01:42 +00:00
.gitmodules fw: init (wip) 2026-10-29 08:40:26 +01:00
CLAUDE.md Untrack __pycache__, add CLAUDE.md 2026-11-08 23:38:30 +00:00
README.md fw: first hardware bring-up, hub configuration works 2026-11-08 18:49:59 +00:00

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_*_OD modes 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_V33 defaults 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 use tcxoVoltage = 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).