Continue documentation

README.md

@@ -20,3 +20,96 @@ A resting state (pause) stops the scanning process when the user does not select
 
 The installation steps described hereafter have been checked on a Raspberry Pi Zero W V1.1, after a fresh install of a 32bit version of Raspbian (bullseye v11, kernel v5.15, release date: April 4th 2022). For Raspbian installation instructions, see [https://www.raspberrypi.com/software/](https://www.raspberrypi.com/software/).
 
+## Required additional modules
+
+* wxPython
+
+This module provides the GUI used by the application. wxPython is available on all standard operating systems, which allows an easy testing and configuration of the software on any computer. To install wxPython execute:
+```
+sudo pip install wxPython
+```
+
+* pypubsub
+
+This python module allows communication between processes through a publish-subscribe mechanism, see [https://pypubsub.readthedocs.io/](https://pypubsub.readthedocs.io/). To install pypubsub execute:
+```
+sudo pip install pypubsub
+```
+
+## HID keyboard configuration
+
+The following configuration steps are strongly inspired by the tutorial available at [http://www.isticktoit.net/?p=1383](http://www.isticktoit.net/?p=1383). The aim is to make the RPi0 appear as a USB keyboard when connected to a host computer.
+
+First, modules must be added to the kernel to enable a device tree overlay:
+```
+echo "dtoverlay=dwc2" | sudo tee -a /boot/config.txt
+echo "dwc2" | sudo tee -a /etc/modules
+echo "libcomposite" | sudo tee -a /etc/modules
+```
+
+Since gadget devices definitions are volatile, the HID keyboard must be created after each boot by a configuration script. To create this script execute:
+```
+sudo touch /usr/bin/cristal-speller
+sudo chmod +x /usr/bin/cristal-speller
+```
+
+Then edit this script using:
+```
+sudo nano /usr/bin/cristal-speller
+```
+and copy/paste the following device definition parameters:
+```
+#!/bin/bash
+cd /sys/kernel/config/usb_gadget/
+# Main
+mkdir -p cristal
+cd cristal
+echo 0x1d6b > idVendor # Linux Foundation
+echo 0x0104 > idProduct # Multifunction Composite Gadget
+echo 0x0100 > bcdDevice # v1.0.0
+echo 0x0200 > bcdUSB # USB2
+# Strings
+mkdir -p strings/0x409
+echo "2022-04-29-0001" > strings/0x409/serialnumber
+echo "CRIStAL" > strings/0x409/manufacturer
+echo "CRIStAL - Univ. Lille - USB Keyboard" > strings/0x409/product
+# Configurations
+mkdir -p configs/config.1/strings/0x409
+echo "Config 1: USB Keyboard" > configs/config.1/strings/0x409/configuration
+echo 400 > configs/config.1/MaxPower
+# Keyboard functions
+mkdir -p functions/hid.usb0
+echo 1 > functions/hid.usb0/protocol
+echo 1 > functions/hid.usb0/subclass
+echo 8 > functions/hid.usb0/report_length
+echo -ne \\x05\\x01\\x09\\x06\\xa1\\x01\\x05\\x07\\x19\\xe0\\x29\\xe7\\x15\\x00\\x25\\x01\\x75\\x01\\x95\\x08\\x81\\x02\\x95\\x01\\x75\\x08\\x81\\x03\\x95\\x05\\x75\\x01\\x05\\x08\\x19\\x01\\x29\\x05\\x91\\x02\\x95\\x01\\x75\\x03\\x91\\x03\\x95\\x06\\x75\\x08\\x15\\x00\\x25\\x65\\x05\\x07\\x19\\x00\\x29\\x65\\x81\\x00\\xc0 > functions/hid.usb0/report_desc
+# Associations
+ln -s functions/hid.usb0 configs/config.1/
+# Activate device
+ls /sys/class/udc > UDC
+```
+Finally, save (`ctrl+O`) and close (`ctrl+X`) the editor.
+
+The device definition script is called at each system startup by the `/etc/rc.local` script. This call is inserted in `/etc/rc.local` just before the `exit` instruction by executing:
+```
+sudo sed -i '/^exit.*/i /usr/bin/cristal-speller # libcomposite configuration' /etc/rc.local
+```
+
+## Application installation
+
+Get a copy of the application from this gitlab page, either using a git clone operation or by downloading the entire project directory in compressed format. Uncompress all the files in a dedicated folder, keeping the directory structure (for instance 'video-audio-speller-master' in the following example). Then in order to start the application after GUI boot, create a shortcut by executing:
+```
+mkdir ~/.config/autostart
+nano ~/.config/autostart/cristal-speller.desktop
+```
+and copy/paste the following shortcut parameters:
+```
+[Desktop Entry]
+Type=Application
+Name=CRIStAL Speller
+Exec=/bin/bash -c 'cd ~/video-audio-speller-main && python speller.py'
+```
+Finally, save (`ctrl+O`) and close (`ctrl+X`) the editor.
+
+You are done! After reboot, your Raspberry Pi Zero should work as indicated at the beginning of this page!
+