TODO - port all of this data over to the HSP page (except /api/debug) and explain how the REST API is mapped to the HSP. Then link to HSP for full details of the calls.
Verb | Meaning |
---|---|
GET | Read value from controller |
PUT | Write value to controller (volatile) |
POST | Write value to controller (non-volatile) |
DELETE | Clear value from controller (volatile) |
Items in italics are for future development. These methods will return a 501 not implemented status code (see status codes for more details).
URI | Verb | Operation |
---|---|---|
/api/main/devicename | GET | Returns the name of the Holoseat device attached to the system |
/api/main/enabled | GET | Returns current enabled state |
/api/main/enabled | PUT | Update enabled state |
/api/main/stepsize | GET | Returns current step size [1-4] |
/api/main/stepsize | PUT | Update current step size [1-4] |
/api/main/profile | GET | Returns current profile name (will end in a * if settings have been updated since profile was set) |
/api/main/profile | PUT | Sets current profile name (cannot end in a '*') Note: sending an empty string as the profile name will suspend configuration update messages until a non-empty profile name is set. |
/api/main/cadence | GET | Returns current cadence (>0 means forward, <0 means reverse) and cadence level [0-4]. See firmware notes for definition of cadence level. |
/api/main/version | GET | Returns hardware, firmware, and HSP version data |
/api/forward | GET | Returns current forward action (see below), returns 404 status if no forward action is active |
/api/forward | PUT | Sets current forward action (see below) |
/api/forward | DELETE | Clears current forward action |
/api/forward/sprint | GET | Returns current forward sprint action (see below), returns 404 status if no forward sprint action is active |
/api/forward/sprint | PUT | Sets current forward sprint action (see below) |
/api/forward/sprint | DELETE | Clears current forward sprint action |
/api/reverse | GET | Returns current reverse action (see below), returns 404 status if no reverse action is active |
/api/reverse | PUT | Sets current reverse action (see below) |
/api/reverse | DELETE | Clears current reverse action |
/api/reverse/sprint | GET | Returns current reverse sprint action (see below), returns 404 status if no forward sprint action is active |
/api/reverse/sprint | PUT | Sets current reverse sprint action (see below) |
/api/reverse/sprint | DELETE | Clears current reverse sprint action |
/api/defaults | GET | Returns current defaults (see below) |
/api/defaults | POST | Sets new defaults (see below) |
/api/defaults | DELETE | Restore factory defaults (see below) |
/api/resistance | GET | Returns current resistance setting of the pedals |
/api/resistance | PUT | Sets current resistance setting of the pedals |
/api/debug | GET | Returns current debug state (True/False) as defined by the service configuration |
/api/debug/serial | PUT | Sends a serial message to Holoseat (returns result as JSON string or status 401 not authorized if debug state is false) |
The JSON format for an action is show below for the default forward action (hold down the 'w' key down on a keyboard)
{ "device": "keyboard", "input": 'w', "command": "hold", "end": "release" }
The default settings for the Holoseat are those settings which are persisted in non-volatile memory. They represent the most generic use case for the Holoseat and as such make a number of assumptions about the default actions associated with pedaling forward and backward.
Specifically, the default settings assume the only device being emulated is a keyboard, with a command/end pairing of hold/release for both the forward and backward actions. Further, the default settings assume there are no sprint actions. These assumptions leave the following minimum set of default settings.
{ "enabled": "True", "stepsize": 2, "forward": 'w', "reverse": 's' }
Note, the default settings are written to the Holoseat controller’s EEPROM which has an expected life of approximately 100,000 write operations. While this should allow for more than sufficient lifespan for the Holoseat controller, we still want to take precautions to avoid malicious code burning through the available write operations. To that end, the POST method on /api/defaults will be protected to only support calls from the application GUI. Additionally, there will be a minimum 5 second timeout that must elapse between calls to update the default settings.