Software Source Code

Version 6 (J. Simmons, 12/23/2016 02:07 pm)

1 2 J. Simmons
h1. Project Software
2 1 J. Simmons
3 2 J. Simmons
{{>toc}}
4 1 J. Simmons
5 2 J. Simmons
h2. Introduction
6 1 J. Simmons
7 2 J. Simmons
The Holoseat project has three software elements.  The first software element is the firmware running on the Holoseat controller.  The second software element is the desktop configuration app.  And the third software element is the test rig software (composed of more firmware and test execution software).  This page covers each of these elements and the serial protocol between the Holoseat controller and the desktop configuration app.
8 1 J. Simmons
9 1 J. Simmons
h2. Controller Firmware
10 2 J. Simmons
11 6 J. Simmons
The Holoseat controller firmware can be found in the "SVN Repository":https://opendesignengine.net/projects/holoseat/repository/show/tags/version-0.3/holoseat_firmware.  It runs on an "Adafruit Feather":https://www.adafruit.com/feather and relies on the "Bounce2":https://github.com/thomasfredericks/Bounce2 library for button "debouncing":https://www.arduino.cc/en/Tutorial/Debounce.  Its function is to detect pedal events from the sensor, use the timing of those events to determine the cadence (in RPM) and direction (forward or backward), and then send the walk command (generally by pressing the 'w' or 's' key) when the pedal speed is greater than the specified trigger cadence.
12 3 J. Simmons
13 4 J. Simmons
The default parameters for the firmware are stored in the @holoseat_constants.h@ file so they will be available at start up without the need for a connection to the desktop configuration app.  The following parameters have default values in the constants file.
14 3 J. Simmons
15 3 J. Simmons
* Default Walk Forward Character - what key is sent to move the character forward in the game
16 3 J. Simmons
* Default Walk Backward Character - what key is sent to move the character backward in the game
17 3 J. Simmons
* Default Holoseat Enabled - is the Holoseat enabled by default?
18 3 J. Simmons
* Default Trigger Cadence - how fast does the user need to pedal (in RPM) to trigger walking?
19 3 J. Simmons
* Default Logging Enabled - is serial logging enabled by default?
20 3 J. Simmons
* Default Logging Interval - how long between messages in serial logging in deci-seconds (0.1 of a second)
21 1 J. Simmons
22 1 J. Simmons
h2. Desktop App
23 1 J. Simmons
24 6 J. Simmons
The Holoseat configuration app can be found in the "SVN Repository":https://opendesignengine.net/projects/holoseat/repository/show/tags/version-0.3/HoloseatConfigurationApp_Win.  It is written in C# and runs in the Windows System Tray (other operating systems will be supported in future releases).  The configuration app requires a locally installed copy of the "Arduino IDE":https://www.arduino.cc/en/Main/Software to update the default parameters in the Holoseat controller and uses the "SerialPortStream 2.0":https://github.com/jcurl/SerialPortStream library to manage the serial communications with the Holoseat controller for live updates to the Holoseat settings.  Its function is to display and modify current settings for the Holoseat and allow users to update the default values for those settings.
25 1 J. Simmons
26 4 J. Simmons
h3. Update Default Parameters
27 4 J. Simmons
28 4 J. Simmons
The configuration app modifies the default parameters by updating the values of the corresponding constants in @holoseat_constants.h@ and then flashing updated firmware to the Holoseat controller.  It is the need to flash the controller with updated firmware that drives the need for a local installation of the Arduino IDE.  If it is not present, the configuration app disables this feature.
29 4 J. Simmons
30 4 J. Simmons
h3. Live Updates to Holoseat Settings
31 4 J. Simmons
32 1 J. Simmons
The configuration app uses the Holoseat Serial Protocol (see below) to display and update the current settings.  These settings will remain in the Holoseat controller until they are changed again using the configuration app or the Holoseat loses power (e.g. when unplugged or the host computer is shutdown).  At which point, the Holoseat reverts to its default parameter values when next used.
33 4 J. Simmons
34 2 J. Simmons
h2. Test Rig Software
35 1 J. Simmons
36 6 J. Simmons
The test rig software can be found in the "SVN Repository":https://opendesignengine.net/projects/holoseat/repository/show/tags/version-0.3/test_rig.  The test rig was developed to support "research into the sensor and magnet pairing":https://opendesignengine.net/boards/36/topics/901.  It is made up of an "Arduino Uno":https://www.arduino.cc/en/Main/ArduinoBoardUno driving a stepper motor.  The stepper motor has an arm attached to it with magnets on the end to simulate users pedaling.  Finally, a Raspberry Pi runs the tests and hosts the sensors under test, receiving signals from the magnets attached to the stepper motor as it turns.  A test case includes a magnet, a sensor, and a simulated pedaling cadence.   
37 5 J. Simmons
38 5 J. Simmons
The test rig software is made up of two components:
39 5 J. Simmons
40 5 J. Simmons
* test rig firmware - running on the Arduino Uno driving a stepper motor
41 5 J. Simmons
* test scripts running on the Raspberry Pi, written in "NodeJS":https://nodejs.org/en/, defining the tests performed with the test rig  
42 5 J. Simmons
43 5 J. Simmons
h3. Test Rig Firmware
44 5 J. Simmons
45 5 J. Simmons
The test rig firmware uses "AccelStepper v1.45":http://www.airspayce.com/mikem/arduino/AccelStepper/index.html to implement an open loop controller on the test rig's stepper motor.  This controller drives the stepper motor at a specified cadence (in rpm).  The cadence is specified as an integer on the serial port.
46 5 J. Simmons
47 5 J. Simmons
h3. Test Scripts
48 5 J. Simmons
49 5 J. Simmons
The test scripts use the "Johnny-Five":http://johnny-five.io/ library to connect to the peripherals required for the test.  The first peripheral is the Arduino running the stepper motor controller (over serial port).  The second peripheral is the sensor under test (over a GPIO port).  Tests are defined first in a csv file.  The generate-test-files.js script converts the csv file listing all of the desired tests into a set of JSON files, each defining a single test.  The scripts run-char-tests.js and run-doe-test.js implement two testing patterns (characterization and Design of Experiments, respectively).  These scripts parse a test definition JSON file and write out test results in a csv time history file.  The set-cadence.js script is a command line tool to set the stepper motor cadence (used before and after tests to start and stop the stepper motor).  The remaining scripts are demonstration tools to verify code was functional before being integrated into the test execution scripts. 
50 2 J. Simmons
51 2 J. Simmons
h2. HoloSeat Serial Protocol
52 2 J. Simmons
53 4 J. Simmons
The HoloSeat firmware has a serial protocol, the Holoseat Serial Protocol (HSP), to enable the desktop configuration app to modify all key parameters and to determine the current configuration of the Holoseat at runtime.
54 2 J. Simmons
55 2 J. Simmons
h3. Protocol Commands
56 2 J. Simmons
57 2 J. Simmons
The HSP supports three commands.  Each command is made up of a single upper case character indicating the statement type.  One command, the (S)et statement, also takes an input string.
58 2 J. Simmons
59 2 J. Simmons
* @?@ - Ready(?) command; used to determine if the HoloSeat is ready to receive commands over the HSP (will reply with the (R)eady message followed by one standard state message if the HoloSeat is ready)
60 2 J. Simmons
* @S <config string>@ - (S)et command; used to send updated configuration to HoloSeat (HoloSeat will reply with @OK@ on success).  The config string has the following format:
61 2 J. Simmons
@<WFC>,<WBC>,<E>,<TC>,<L>,<LI>@ - example: @S w,s,0,60,0,20@
62 2 J. Simmons
** @<WFC>@ - Walk forward character (example: w)
63 2 J. Simmons
** @<WBC>@ - Walk backward character (example: s)
64 2 J. Simmons
** @<E>@ - Enabled? Must be a @0@ (disabled) or a @1@ (enabled) (example: 1)
65 2 J. Simmons
** @<TC>@ - Trigger cadence (example: 65)
66 2 J. Simmons
** @<L>@ - Logging enabled? Must be a @0@ (disabled) or a @1@ (enabled) (example: 1)
67 2 J. Simmons
** @<LI>@ - Logging interval in deci-seconds (example: 10)
68 2 J. Simmons
* @Q@ - (Q)uery command; used to request the HoloSeat send one standard state message (see *Protocol Messages* below)
69 2 J. Simmons
70 2 J. Simmons
h3. Protocol Messages
71 2 J. Simmons
72 2 J. Simmons
The HSP has two messages.  One is a single character message similar to the commands and one is the HSP standard state message which is sent after initialization, in reply to a (Q)uery command, and as the serial logging message.
73 2 J. Simmons
74 2 J. Simmons
* @R@ - (R)eady; sent by the HoloSeat to indicate it is ready for serial communication; sent in reply to the Ready(?) command and when serial port is attached in debug mode (to be added)
75 2 J. Simmons
* @<VER>,<WFC>(<DWFC>),<WBC>(<DWBC>),<E>(<DE>),<C>/<TC>(<DTC>),<L>(<DL>)/<LI>(<DLI>)@ - standard state message, see below for key; example: @1.2.3,w(w),s(s),1(1),70/65(75),1(0)/10(10)@
76 2 J. Simmons
** @<VER>@ - Firmware version string (example: 1.2.3)
77 2 J. Simmons
** @<WFC>@ - Walk forward character (example: w)
78 2 J. Simmons
** @<DWFC>@ - Default walk forward character (example: w)
79 2 J. Simmons
** @<WBC>@ - Walk backward character (example: s)
80 2 J. Simmons
** @<DWBC>@ - Default walk backward character (example: s)
81 2 J. Simmons
** @<E>@ - Enabled? Must be a @0@ (disabled) or a @1@ (enabled) (example: 1)
82 2 J. Simmons
** @<DE>@ - Default enabled state, same format as @<E>@ (example: 1)
83 2 J. Simmons
** @<C>@ - Current cadence rounded to whole number; positive value means direction is forward, negative value means direction is backward (example: 70)
84 2 J. Simmons
** @<TC>@ - Trigger cadence (example: 65)
85 2 J. Simmons
** @<DTC>@ - Default trigger cadence (example: 75)
86 2 J. Simmons
** @<L>@ - Logging enabled? Must be a @0@ (disabled) or a @1@ (enabled) (example: 1)
87 2 J. Simmons
** @<DL>@ - Default logging enabled,  same format as @<L>@ (example: 0)
88 2 J. Simmons
** @<LI>@ - Logging interval in deci-seconds (example: 10)
89 2 J. Simmons
** @<DLI>@ - Default logging interval in deci-seconds (example: 10)
90 2 J. Simmons
91 2 J. Simmons
h3. Protocol Usage
92 2 J. Simmons
93 2 J. Simmons
Always start a serial session by sending a Ready(?) command.  If a (R)eady message is not received, wait and try again until a timeout is reached or a (R)eady message is received.  Be sure to check the version string sent in the initial standard state message to ensure your app is compatible with the version of the HoloSeat firmware.  
94 2 J. Simmons
95 2 J. Simmons
After you have initialized your connection, you can then use the (Set) and (Q)uery commands as necessary to control and observe the HoloSeat's state.