Xebow is a nerves-based firmware for the Keybow keypad.
This project is in early development. Features and the API may be subject to change.
Resources:
- Join the
#nerves-keyboardchannel on the elixir-lang Slack to chat with us and keep up on the latest developments. - Visit the wiki to see past meeting notes and other content.
- Planning meetings are open to all. Feel free to join if you would like to familiarize yourself with the internals of Xebow or would like to find a place to help out. The schedule is pinned in the Slack channel.
- Wireframes are available on Figma.
$ git clone git@github.com:ElixirSeattle/xebow.git
$ cd xebow
If you would like to flash firmware to the MicroSD card without having to remove it from the keybow each time, you will need to set up SSH access. This also provides access to a running iex shell for running commands directly on the device.
If your SSH public key is not in your home directory's .ssh/ directory with one
of the following names, then you can specify the path to your public key by
setting the NERVES_SSH_PUB_KEY environment variable:
- id_rsa.pub
- id_ecdsa.pub
- id_ed25519.pub
If you have not used nerves to build firmware before, you may need to install several dependencies. See the installation guide if this is your first time using nerves.
The keybow uses a Raspberry Pi Zero WH, so the target would be rpi0. However,
to better support all the keybow features that xebow uses, a custom target has
been setup called keybow that you will need to use instead. To build and burn
the firmware:
$ export MIX_TARGET=keybow
$ mix deps.get
$ mix firmware
Insert the MicroSD card into an card reader attached to your computer and then run:
$ mix firmware.burn
The mix firmware.burn command will try to detect your MicroSD card and offer
to write the data to the card. IMPORTANT: Triple-check that the device it
plans to write to is the MicroSD Card, or you could permanently delete data on
another device.
Remove the MicroSD card and insert it into the keybow. Plug the keybow into the computer and wait for it to boot. Once booted, the keypad should begin cycling all keys through a rainbow of colors.
The firmware can be updated while the Keybow is attached to your computer as long as the Xebow firmware is running on it.
Build the firmware and upload it via SSH by running:
$ mix firmware.upload
If you would like to perform these steps individually, use mix firmware
and mix upload.
Notes
- The upload needs to be run on a computer with the same SSH public key that was used when burning the SD card or else it won't be able to connect to the Keybow.
- If the
xebow.localhostname can't be resolved, try unplugging the Keybow from the USB port, wait for the computer's USB disconnect notification, then plug the Keybow back in and try again after it's booted back up.
The following instructions are for running the Xebow web interface on your computer for a faster development cycle.
If this is your first time running the web interface, set up the web app with:
$ mix setup
Start the web interface, which will be available at http://localhost:4000:
$ mix phx.server
The xebow firmware sets up the keybow as a 10-key numpad. Turn the keypad so the flashing LEDs are on the left of each key and the USB cord is facing right. In this position, the keypad has the following layout:
+-----+-----+-----+
| 7 | 8 | 9 |
+-----+-----+-----+
| 4 | 5 | 6 |
+-----+-----+-----+
| 1 | 2 | 3 |
+-----+-----+-----+
| 0 | L-1 | L-2 |
+-----+-----+-----+
The L-1 and L-2 keys activate different "layers" of the keypad, which allows
mapping additional commands to each key. For example, holding L-2 and hitting
7 will trigger a command to flash the keypad red.
L-1+9: volume upL-1+6: volume downL-1+8: muteL-2+7: flash keypad redL-2+9: flash keypad greenL-2+4: previous animationL-2+6: next animation