Skip to content
Power control system with USB interface, built using off-the-shelf microcontroller and relay boards
C Makefile Shell
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
libopencm3 @ 7e1d3da
librfn @ 6bc06dc

usb-relay - USB relay control module

usb-relay is a quick 'n dirty relay controller based on two very cheap off-the-shelf boards.

Assembled usb-relay device

Quickstart for STM32F103 boards

  • Install the Arm Embedded Toolchain (or similar arm-none-eabi- compiler), openocd and dfu-util.
  • Clone this repo: git clone
  • Fetch the libraries: cd usb-relay; git submodule update --init --recursive
  • Build the firmware: make
  • Use JTAG/SWD programmer to install the booloader. Either make -C src/bootloader flash for STLink v2 or make -C src/bootloader BMP_PORT=/dev/ttyACM0 flash for a Black Magic Probe.
  • Use the bootloader to install the main application using the microcontroller board's own USB socket: make -C src/stm32f1-relay flash

Hardware setup

The firmware can be easily ported but has been most heavily tested on STM32F103C8T6 based breakout boards. Connections required are:

  • USB to host computer
  • 5v and GND to relay board
  • GPIOB 12-15 -> relay 1-4
  • GPIOA 8-10 -> relay 5-7
  • GPIOB 6 -> relay 8

All the GPIO connections are on one side of the controller board (and the first seven are sequentially allocated).

Alternative boards

  • Carbon by Seeed and 96Boards.
  • STM32F4-Discovery (undocumented)
  • Most STM32F103 breakout boards have jumpers enabling them to permanently assert USB hotplug. If your board does not do this then you will likely have to configure a GPIO pin to assert hotplug. usb-relay does not contain code for this. Adding it is an exercise for the reader!


The firmware registers itself as a CDC-ACM device and, under Linux, will be presented as ttyACMx where x is typically 0 on "simple" machines although will be larger if there is any USB communication or modem device installed (for example an unused 3G modem).

Type help to get a list of available commands. On STM32F1 platforms the commands available are:

  • echo - test command that echos back its input
  • id - reports a unique device serial number (the same number is also reported as the USB serial number)
  • help - shows a list of commands
  • led - manipulate the LED on the board (for testing, takes the same arguments as the relay command)
  • reboot - reboot into DFU mode to allows a firmware upgrade (firmware upgrade mode can also be triggered by resetting the board whilst leaving it plugged into the host)
  • relay1 to relay8 - can be used to turn the relay on or off as well as toggling its state or sending a 1 second pulse
  • version - reports firmware version and build date
  • uptime - show time since power on

udev rules

The firmware uses the STM32 unique device ID to provide every physical instance with a unique serial number. This allows udev rules to be introduced to ensure stable device enumeration regardless of any changes to the USB topology.

SUBSYSTEM=="tty", ATTRS{manufacturer}=="", ATTRS{serial}=="045101780587252555FFC660", SYMLINK+="ttyrelayC660"
SUBSYSTEM=="tty", ATTRS{manufacturer}=="", ATTRS{serial}=="7301C2152B72E52DE2744F3B", SYMLINK+="ttyrelay4F3B"

The serial number can picked up from the kernel log (dmesg) or using udevadm: udevadm info --attribute-walk /dev/ttyACM0 | grep serial .

udevadm can also be used to re-apply the rule if any changes are made to the symlink: sudo udevadm trigger /dev/ttyACM0

Example hardware

usb-relay should readily port to most STM32-based microcontroller boards. However the following example hardware is easily (and cheaply) availabe and will work out-of-the-box.

STM32F103C8T6 microcontroller development board from Normally very easy to source on eBay.

STM32F103C8T6 microcontroller development

Eight channel relay board from specialist supplier (or eBay)

Eight channel relay board

You can’t perform that action at this time.