HIDRelayController

hid-relay

Open source design for HID controlled relay

This project provides an Open Source and Open Hardware implementation of the HID Relay board. These boards can be found for purchase from various vendors, and appear as a USB HID device. They can be controlled using either pyhid-usb-relay or usb-relay-hid.

The software aims to be 100% compatible with the board that can be purchased, allowing custom designed boards to be interchanged with the same host side control software (and possibly to even control things other than relays).

The main controller for the relay boards is some sort of Atmel AVR chip. The software uses the V-USB project to implement the USB protocol, and should be able to run on any chip that V-USB supports.

Quick Install

1. Install avrdude (e.g. sudo apt install avrdude)
2. Go to the releases page and download the flash.hex, eeprom.hex and fuses.txt files for the device you want to program
3. Connect your AVR In System Programmer (ISP) to the relay device, and it with the command:

avrdude -P <MY_PROGRAMMER> $(cat fuses.txt)

4. Write the main program code and eeprom to the device by using the command:

avrdude -P <MY_PROGRAMMER> -p <MY_DEVICE> \
  -U flash:w:flash.hex:i \
  -U eeprom:w:eeprom.hex:i

Compiling

meson is used as the build configuration system for this project. In order to start compiling, you must first define a meson cross file to tell meson about the board you are targeting. The project comes with cross files for the included hardware designs and other platforms which can be found in the cross/ directory. If you are using a custom hardware design, look at these as a reference for how to define your own board.

Once you have a cross file that describes your board, configure the build with the command:

meson setup --cross-file path/to/my_cross.txt build

Once this is complete, the main program can be built with:

ninja -C build

Flashing Software

The meson configure for this project contains several convenience commands to help program a board after the software is built. The commands use the avrdude program to interact with the board. By default, meson assumes you are using a USB AVRISP MKII programmer, but this can be changed with the avrdude_programmer and avrdude_port meson options, for example:

meson configure build -Davrdude_programmer=buspirate

The helper targets defined in meson are all invoked using the meson compile command, like:

meson compile -C build COMMAND

Or with ninja:

ninja -C build COMMAND

The included commands are:

The writefuses command can be particularly useful to provision a new fresh AVR, as it runs at a slow speed so it can correctly program a device even if it is still running slowly on the internal oscillator (the default from the factory).

Thus, to program your board after compiling, run:

# Uncomment this line if this is a fresh chip that has never been programmed before
# ninja -C build writefuses
ninja -C build writeflash

NOTE: Be careful when programming fuses as incorrect fuses can cause the AVR to be unprogrammable, which can only be corrected using High Voltage Serial Programming.