Hacktivity 2019 badge quickstart guide
Your badge is a small computer: it has persistent Flash storage, RAM, a display, some buttons and interfaces with the outside world. There are two ways to interact with it, the aforementioned display and buttons is the simplest solution, while the USB allows more possibilities.
Display and buttons
The display and buttons can be used without a computer and work a bit like your feature phone from the early 2000s. Menu items displayed on the little backlit monochrome screen can be navigated using the directional keys (up, down, left, right) and control keys (exit and enter).
The buttons are not your standard mechanical keys but are each rather made up of two conductive parts. When your finger touches both parts of the same key, the badge detects this as a single key press. You have to remove your finger to allow the same key to be pressed again, so there’s no repeat like on your PC keyboard.
When you turn on the device by connecting it to a USB power supply (power bank, phone charger, PC, etc.) or setting the switch below the battery holder into the Battery ON position, after some loading the main menu is presented. In this main menu, some built-in apps are listed and you can install more using the app store installer. This uses Wi-Fi which works out of the box during the conference and you can update these Wi-Fi settings afterwards using either this UI or over USB.
The USB interface works a bit like an oldschool terminal: you hook up a computer and the keys pressed in a terminal emulator are transmitted to the badge, while the response is displayed within the emulator window. Through this you can access a Python-like REPL and you can also use it to upload and download files, bypassing the app store.
When you connect your badge to a Linux box or VM, you’ll see something like this in the output of dmesg:
usb 2-3: New USB device found, idVendor=239a, idProduct=8018, bcdDevice= 1.00 usb 2-3: New USB device strings: Mfr=1, Product=2, SerialNumber=3 usb 2-3: Product: Hacktivity Badge 2019 usb 2-3: Manufacturer: Hacktivity2019 usb 2-3: SerialNumber: HACKTIVITY, the biggest event of its kind in Central & Eastern Europe cdc_acm 2-3:1.0: ttyACM0: USB ACM device
The last line contains the name of the device, and the easiest way to interact with it is using screen, which is usually either already installed on most distros or can be easily installed. Opening a shell is just a simple command:
$ screen /dev/ttyACM0 115200
The first parameter contains the device name, which should be updated if your dmesg output contained something else. The second parameter is the baud rate (the number of bits transmitted per second), this should be left at this default value unless you tampered with your device (in which case you already know what you’re doing ;)).
If all goes well, you might get an empty screen. In this case, press Enter and you’ll be greeted with a Python shell.
Welcome to the python shell of your badge! Check out https://wiki.badge.team/ for instructions. >>>
You can exit this shell by using C-d (Control + D) which will bring you back to a menu that can be controlled with the arrow keys and Enter. You can exit your local screen session by pressing C-a (Control + A) then d (for Detach).
If you only see the following message
$ screen /dev/ttyACM0 115200 [screen is terminating]
you might have an issue with privileges regarding the serial port. In this case, you might want to put your user into the same group as the device file. Another option is to run screen as root, which is fine for first trials but might be problematic on the long run.
The badge runs a small operating system which can and should be updated every once in a while, especially in the first week after you get the badge as we the organizers are working around the clock trying to work out issues and improve the overall quality.
Updating the firmware can be done both on the menu-based button-display UI or using the console menu system over USB. They work the same way and require Wi-Fi connectivity, which (as described above) works out of the box during the event.
Installing and uninsalling apps from the store
While most of the app store is pretty intuitive, there are a few nifty tricks. The app store listings are only updated when the user asks for it: this can be done by pressing the left arrow key while in the app store installer.
The top-level main menu contains the item “Update apps”, this on the other hand updates all apps you already have installed on the device.
Apps can be uninstalled by going to the top-level main menu, navigating the selection onto the app you want to remove and pressing the left arrow key. A confirmation is shown, pressing Enter performs the actual removal of the selected app.
The app store itself: the Hatchery
The app store is called Hatchery and it can be found at https://badge.hacktivity.com both by web browsers and the badges themselves. Apps are collections of Python scripts and are stored in the app store in a source code form. Anyone can upload apps to the store after a free and open registration step, and everybody can see the source code of all the apps.
This way, you can learn from others and quickly get started with your own app — first by modifying an existing app, and later realizing that you introduced so many changes that you just created your own app. When in doubt, you can always use the REPL (read-eval-print loop) over the USB interface to just try what a certain line of code does on the device.