History

HSP Over REST API

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.

Meaning of HTTP Verbs

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)

REST API

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)

Specifying an Action

Actions are composed of 4 parts:
  1. Device [keyboard|mouse|joypad] - what device is being emulated to implement this action
    #Input - what input value (e.g. key on a keyboard or button on a mouse) is being activated by the command
  2. Command [press|hold] - how the input value should be sent:
    press = press and release the input (e.g. press a key on a keyboard or click a mouse button)
    hold = press and hold the input (e.g. hold down a key on a keyboard or a button on a mouse)
  3. End [release|repeat|noop] - how to end the action
    release = release the held input (requires command 'hold')
    repeat = repeat the action to end the action (requires command 'press')
    noop = no steps required to end the action, it will timeout in game (requires command == 'press')

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" 
}

Defaults

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.

  1. Enabled [True|False] - whether the Holoseat starts in the enabled state or not
  2. Step Size [1-4] - the relative length of single steps (smaller values yield shorter steps)
  3. Forward Character [alphanumeric character] - the key to press as the default forward action
  4. Reverse Character [alphanumeric character] - the key to press as the default reverse action

    The JSON format for default settings is show below for the factory defaults.
{
"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.

Also available in: HTML TXT