HSP Over REST API

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.

URI Verb Operation
/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 *)
/api/main/cadence GET Returns current cadence (>0 means forward, <0 means reverse)
/api/forward GET Returns current forward action (see below), returns “None” if no forward sprint 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 “None” 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 action
/api/reverse GET Returns current reverse action (see below), returns “None” if no forward sprint 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 “None” if no forward sprint action is active
/api/reverse/sprint PUT Sets current reverse sprint action (see below)
/api/reverse/sprint DELETE Clears reverse forward 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

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.