HSP Over REST API¶

• HSP Over REST API
  • Meaning of HTTP Verbs
  • REST API
  • Specifying an Action
  • Defaults

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/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 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

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.