Install Arduino support on FreeBSD

The Arduino system has been designed to be accessible to people at all skill levels, and Keyboardio is built on top of the Arduino platform because we share that goal. There are many ways to set up your system to work with the Keyboardio firmware, the most typical is to use the Arduino Integrated Development Environment (IDE); an application that gives some visual context to the code you want to send to your Arduino device. This is the easiest process for folks who are new to Arduino, or to programming generally. If you follow the instructions below step by step you should be fine. :-)

Step One: installing support packages

1. Install the following packages required by the build system: bash, gmake, perl5, avrdude, and arduino18.

   $ sudo pkg install bash gmake perl5 avrdude arduino18

2. Flashing firmware as non-root.

   a. If you want to flash your firmware as non-root, ensure your user has write access to the appropriate USB devices in devfs. By default, the devices are owned by root:operator, so put yourself in the operator group. You will also need to add yourself to the dialer group to use the modem device:

   $ sudo pw groupmod operator -m $USER
   $ sudo pw groupmod dialer -m $USER

   b. Add devfs rules for write access for operator to USB devices:

   $ cat << EOM >> /etc/devfs.rules
   #
   # Allow operators access to usb devices.
   #
   [operator_usb=5]
   add path usbctl mode 0660 group operator
   add path 'usb/*' mode 0660 group operator
   add path 'ugen*' mode 0660 group operator
   EOM

   c. Update /etc/rc.conf to use the new devfs rule as the system rule:

   $ sudo sysrc devfs_system_ruleset=operator_usb

   d. Restart devfs:

   $ sudo service devfs restart

Step Two: retrieve your firmware.

1. Check out the Keyboardio-Bundle according to the existing documentation.

Step three: compiling the firmware and flashing the keyboard.

1. Edit your sketch or copy one of the examples from $HOME/Arduino/hardware/keyboardio/avr/libraries/Kaleidoscope/examples.

2. Flash the firmware:

   $ cd $HOME/Arduino/Model01-Firmware
   $ gmake flash

Congrats, you've just installed the latest firmware!!

FreeBSD Boot Protocol

If your keyboard is recognised in dmesg output, but doesn't work once the kernel is loaded, you may need to switch the firmware's default operating mode to HID BOOT PROTOCOL like so:

diff --git src/BootKeyboard/BootKeyboard.h src/BootKeyboard/BootKeyboard.h
index 3cfe7b1..85d077a 100644
--- src/BootKeyboard/BootKeyboard.h
+++ src/BootKeyboard/BootKeyboard.h
@@ -65,7 +65,7 @@ class BootKeyboard_ : public PluggableUSBModule {
     uint8_t getProtocol(void);
     void setProtocol(uint8_t protocol);
 
-    uint8_t default_protocol = HID_REPORT_PROTOCOL;
+    uint8_t default_protocol = HID_BOOT_PROTOCOL;
 
   protected:
     HID_BootKeyboardReport_Data_t _keyReport, _lastKeyReport;

Next step: Edit a Keymap