martyv2:documentation:advanced:rest

The REST API supports conventional GET and POST operations.

Request format

For WiFi HTTP requests, start the URL with:

http://<ipaddrorname>/api/

For example:

http://mymarty/api/v

Over other interfaces, such as BLE and CommandSerial, wrap the command in a RICFrame or RICSerial message. Omit the api prefix and include a leading forward slash:

/v

Choose a command from the sections below. Request examples are shown without the WiFi HTTP prefix; use the format above for your interface.

System, network and power commands

v

Method: GET

URL pattern:

Get the system name and version of RIC

Example request:

Example response:

{"req":"v","rslt":"ok","SystemName":"RIC","SystemVersion":"1.0.25","SerialNo":"0123456789abcdef0123456789abcdef","MAC":"A4CF129ED5F6","RicHwRevNo":1}

friendlyname

Method: GET

URL pattern:

friendlyname

Get or set the robot friendly name.

To return to the system generated name set a blank name using the request friendlyname/ - this also sets the persisted “friendlyNameIsSet” state to indicate name is not set

Example request:

friendlyname
OR
friendlyname/My Marty
OR
friendlyname/

Example response:

{"req":"friendlyname","friendlyName":"MyMarty","friendlyNameIsSet":1,"rslt":"ok"}
OR
{"req":"friendlyname/MyMarty","friendlyName":"MyMarty","friendlyNameIsSet":1,"rslt":"ok"}
OR
{"req":"friendlyname/","friendlyName":"Marty_9ED5F6","friendlyNameIsSet":0,"rslt":"ok"}

w

Method: GET

URL pattern:

w/<ssid>/<password>
OR
w/<ssid>/<password>/<hostname>

Specify WiFi credentials.

WiFi SSID is limited to 31 (not 32) chars. Password is limited to 63 (not 64) chars.

Valid SSID chars include:

~!@#$^*()-={}[:;<>?,.`Aa1 %&_\/

And valid Password chars include:

~!@#$^*()-={}[:;<>?,.`A1 %&_]+"\/

HTTP encoded chars are also fine so to include a backslash you would need to enter %2F and to include a forwardslash would be %5C

On networks supporting mDNS defining the hostname can allow some browsers (for instance Chrome) to access by name

Example request:

w/myssid/mypassword/marty

Example response:

{"req":"w/myssid/mypassword/marty","rslt":"ok"}

wc

Method: GET

URL pattern:

wc/<norestart>

Clear WiFi credentials and disconnect WiFi

Note that if the norestart option is not specified the system will restart if this command succeeds.

Example request:

wc
OR
wc/norestart

Example response:

{"req":"wc","rslt":"ok"}
{"req":"wc/norestart","rslt":"ok"}

reset

Method: GET

URL pattern:

reset

Schedule a reset in around 1 second

Example request:

reset

Example response:

{"req":"reset","rslt":"ok"}

serialno

Method: GET

URL pattern:

serialno

Set/get serial number

Serial number is a 16 byte value (sent/received hex formatted)

Setting requires the additional value “RoboticalMagic”

Example request:

serialno
or
serialno/01234567890ABCDEF0123456789ABCDEF/RoboticalMagic

Example response:

{"req":"serialno","SerialNo":"0123456789abcdef0123456789abcdef","rslt":"ok"}
{"req":"serialno/01234567890ABCDEF0123456789ABCDEF/RoboticalMagic","SerialNo":"01234567890abcdef0123456789abcde","rslt":"ok"}

hwrevno

Method: GET

URL pattern:

hwrevno

Get RIC hardware revision number

The HW revision number is a positive integer

Example request:

hwrevno

Example response:

{"req":"hwrevno","RicHwRevNo":2,"rslt":"ok"}

pwrctrl

Method: GET

URL pattern:

pwrctrl

Power control of the robot

setChgEn will only have an effect on batch 2 hardware onwards, where it will disable battery charging and allow the battery to fully power the 5v line while the robot is plugged in - otherwise the battery will get unhappy if more current is drawn than is supplied while charging (max 500mA)

pwrCycleEn can be used for testing - disabling power cycling disables I2C bus recovery and can be used to test add-ons

pwrOffEn can be used for testing - disabling ensures 5V power is not turned off (due to timeout or battery levels, etc) - NOTE: does not disable firmware update 5V changes or user/externally requested changes

fullShutdownEn can be used for testing - it can disable the final stage of shutdown - thus leaving the ESP32 running in all cases

setExtPower can be used to control the external power (on the EXTENSION connector used to connect a Raspberry Pi, etc)

Example request:

pwrctrl/5von
OR
pwrctrl/5voff
OR
pwrctrl/off
OR
pwrctrl/setChgEn/0
pwrctrl/setChgEn/1
OR
pwrctrl/pwrCycleEn/0
pwrctrl/pwrCycleEn/1
OR
pwrctrl/pwrOffEn/0
pwrctrl/pwrOffEn/1
OR
pwrctrl/fullShutdownEn/0
pwrctrl/fullShutdownEn/1
OR
pwrctrl/setExtPower/0
pwrctrl/setExtPower/1

Example response:

{"req":"pwrctrl/5von","rslt":"ok"}

Motion, programs and audio

traj

Method: GET

URL pattern:

traj

Start generation of a trajectory

Trajectories are stored in files on the file system. They have the extension .trj and the positional parameter to the REST command is the base name of the file (excluding the .trj part)

Parameters to be used when generating the trajectory are supplied using the standard ?a=1&b=2 syntax used with web API queries, etc.

Example request:

traj/test?aaa=1&bbb=2&ccc=3

Example response:

{"req":"traj/test?aaa=1&bbb=2&ccc=3","rslt":"ok"}

pyrun

Method: GET

URL pattern:

pyrun

Run a micropython program

The procCtrl parameters are optional and indicate:

noclear - the queue of programs waiting to be run is not cleared - so this program is added to the end of the queue and other programs in the queue will need to finish before this one runs
nostop - don’t stop execution of any running python program. If a program is running then this program is added to a queue (see noclear above). In this case any running python program will need to finish before the queue is processed.

Example request:

pyrun/screenfree.py
OR
pyrun/screenfree.py?procCtrl=noclear+nostop

Example response:

{"req":"pyrun/screenfree.py","rslt":"ok"}

pystop

Method: GET

URL pattern:

pystop

Stop running micropython program and/or manage the queue of programs

With no parameters any running micropython program is stopped and the queue is cleared

The procCtrl parameter is described in pyrun command

Example request:

pystop
OR
pystop?procCtrl=noclear+nostop

Example response:

{"req":"pystop","rslt":"ok"}

pystatus

Method: GET

URL pattern:

pystatus

Get the name of the currently running micropython program (or blank if nothing running)

Example request:

pystatus

Example response:

{"req":"pystatus","running":"screenfree.py","rslt":"ok"}

audio / vol

Method: GET

URL pattern:

audio/vol
audio/vol/vPC

Get / set audio volume. Volume is in percent. With no additional args gets the volume. With one arg sets the volume.

Example request:

audio/vol
audio/vol/60

Example response:

{"req":"audio/vol","volPC":100,"rslt":"ok"}
{"req":"audio/vol/60","rslt":"ok"}

audio / pause

Method: GET

URL pattern:

audio/pause
audio/resume
audio/stop

pause/resume/stop audio playback.

Example request:

audio/pause
audio/resume
audio/stop

robot

Method: GET

URL pattern:

robot

stop - stops immediately, clears all motion queues

stopAfterMove - stops after any currently in-progress movement

panic - stops immediately and resets HWElems

pause - pauses motion

resume - resumes motion

Example request:

robot/stop
robot/stopAfterMove
robot/panic
robot/pause
robot/resume

Example response:

{"req":"robot/stop","rslt":"ok"}

Files

filerun

Method: GET

URL pattern:

filerun/<fileName>
OR
filerun/sd~<fileName>
OR
filerun/local~<fileName>

Run a file on RIC

This includes playing a sound (filename must end .raw) and running a Micropython program (filename ends .py)

Two file systems are supported: local (stored in flash on the ESP32) and SD (if an external SD card is present). The first part of the path can specify a file system followed by ~. If no file system is specified the default one is used which is generally local. The prefix spiffs~ can be used instead of local~.

Example request:

filerun/confused.raw

Example response:

{"req":"filerun/confused.raw","rslt":"ok"}

filelist

Method: GET

URL pattern:

filelist
OR
filelist/local
OR
filelist/sd

List the files and get file system info on a file system.

See notes about file systems in filerun

“spiffs” can be used interchangeably with “local” as the name of the local file system

Example request:

filelist

Example response:

{"req":"filelist","rslt":"ok","fsName":"local","fsBase":"/local","diskSize":892556.00,"diskUsed":111946.00,"folder":"/local/","files":[{"name":"test4.trj","size":317},{"name":"lowerFoot.trj","size":206},{"name":"test.trj","size":2921},{"name":"home.js","size":41031},{"name":"hold.trj","size":514},{"name":"sidefall.trj","size":1083},{"name":"kick.trj","size":2817},{"name":"home.css","size":14861},{"name":"standStraight.trj","size":409},{"name":"atari.raw","size":5960},{"name":"eyesWide.trj","size":58},{"name":"joint.trj","size":73},{"name":"wave.trj","size":389},{"name":"eyesExcited.trj","size":58},{"name":"circle.trj","size":1308},{"name":"favicon.ico","size":1150},{"name":"test3.trj","size":668},{"name":"liftFoot.trj","size":308},{"name":"eyesAngry.trj","size":59},{"name":"stm8-servoboard.sfw","size":6249},{"name":"wiggle.trj","size":2066},{"name":"eyesNormal.trj","size":57},{"name":"test2.trj","size":1170},{"name":"step.trj","size":2229},{"name":"demo.trj","size":2871},{"name":"wiggleEyes.trj","size":292},{"name":"sidestep.trj","size":1223},{"name":"index.html","size":8231},{"name":"lean.trj","size":603},{"name":"getReady.trj","size":759}]}

fileread

Method: GET

URL pattern:

fileread/local/<fileName>
OR
fileread/sd/<fileName>

Read a text file from file system

“spiffs” can be used interchangeably with “local” as the name of the local file system

Example request:

fileread/local/home.css

Example response:

… the text content of the file …

filedelete

Method: GET

URL pattern:

filedelete/local/<fileName>
OR
filedelete/sd/<fileName>

Delete a file from file system

“spiffs” can be used interchangeably with “local” as the name of the local file system

Example request:

filedelete/local/test.txt

Example response:

{"req":"filedelete/local/test.txt","rslt":"ok"}
OR
{"req":"filedelete/local/test.txt","rslt":"fail"}

fileupload

Method: POST

URL pattern:

fileupload

Upload a file

Note: this API endpoint is only directly usable from HTTP. Other protocols are documented to use the elements of this endpoint in RICREST Protocol

Example response:

Uses the regular HTTP file upload protocol

System module information

sysmodinfo

Method: GET

URL pattern:

sysmodinfo

Get info about a module of the system (SysMod) by name. SysMod names which support this API are (case sensitive):

NetMan

BLEMan

SysMan

Example request:

sysmodinfo/NetMan
sysmodinfo/BLEMan

Example response:

{“rslt”:”ok”,"isConn":1,"connState":"WiFiAndIP","SSID":"rdint01","IP":"192.168.86.136","Hostname":""}
OR
{“rslt”:”ok”,"isConn":0,"isAdv":1,"advName":"Marty","rssi":0}
OR
{“rslt”:”ok”,"isConn":1,"isAdv":0,"advName":"Marty","rssi":-43}

sysmoddebug

Method: GET

URL pattern:

sysmoddebug

Get debug info about a SysMod by name, SysMod names that are valid include:

SysMan

Example request:

sysmoddebug/RobotCtrl

Example response:

{"req":"sysmoddebug/RobotCtrl","debugStr":"["Bus":{"count":1148319,"respFull":2,"polls":22034,"cmds":11345},{"IMU":{"fresh":1,"x":0.13,"y":0.05,"z":0.98}},{"FuelGauge":{"fresh":0}},{}]","rslt":"ok"}

Hardware status

hwstatus

Method: GET

URL pattern:

hwstatus?filterByType=nnnn

Get the status of all hardware elements

filterByType=nnnn allows filtering by a specific type or whoAmITypeCode, nnnn can be any value that appears under "type", "whoAmITypeCode" or "whoAmI" keys in the response. For example:

SmartServo
IMU
FuelGauge
RSAddOn
coloursensor
AABBCCDD

In the above, AABBCCDD is the hex (with leading zeroes) format of the 32 bit whoAmITypeCode. For normal addons this is the first four hex digits are 0000 and the other four hex digits come from the 16 bit number that add-ons report at the beginning of their WhoAmI report. For other add-ons the type code is:

FuelGauge: 1000 + type reported by chip
IMU: 1001 + type reported by chip
BusPixels: 1002 + type reported by chip
PowerControl: 1003 + type reported by chip

See https://robotical.atlassian.net/wiki/spaces/M2/pages/1371013143/HW+Identifiers+Device+Type+IDs#Device-Type-ID-%26-Whoami for more whoami (type code) values.

The nnnn value above can also be a list of types separated by commas (for example filterByType=SmartServos,IMU)

Furthermore, an exclamation mark ! can be added as the first character of the nnnn and this will invert the logic (so, for example filterByType=!SmartServos,IMU) - the example would return all HWElems that are not SmartServos or IMUs

Example request:

hwstatus

Example response:

{
    "req": "hwstatus",
    "hw": [
        {
            "name": "RightTwist", "type": "SmartServo",
            "busName": "I2CA", "addr": "0x14", "addrValid": 1,
            "IDNo": 4,
            "whoAmI": "RTwistMotor", "whoAmITypeCode": "0000008b",
            "SN": "228f0fbc5bbe7b24", "versionStr": "1.0.0",
            "commsOk": "Y"
        },
        {
            "name": "IMU0", "type": "IMU",
            "busName": "I2CA", "addr": "0x1d", "addrValid": 1,
            "IDNo": 19,
            "whoAmI": "MMA8452Q", "whoAmITypeCode": "10018452",
            "SN": "", "versionStr": "0.0.0",
            "commsOk": "Y"
        },
        {
            "name": "AddOn_I2CA_0F", "type": "RSAddOn",
            "busName": "I2CA", "addr": "0x0f", "addrValid": 1,
            "IDNo": 35,
            "whoAmI": "coloursensor", "whoAmITypeCode": "00000085",
            "SN": "385a845b77abf0ec", "versionStr": "1.1.1",
            "commsOk": "Y"
        }
    ],
    "rslt": "ok"
}

hwstatus / name

Method: GET

URL pattern:

hwstatus/name?filterByType=nnnn

Get the names of all hardware elements

Example request:

hwstatus/name

Example response:

{"req":"hwstatus/name","hw":["LeftHip","LeftTwist","LeftKnee","RightHip","RightTwist","RightKnee","LeftArm","RightArm","Eyes","IMU0","AudioOut","BusPixels0","FuelGauge0","PowerCtrl"],"rslt":"ok"}

hwstatus / status

Method: GET

URL pattern:

hwstatus/status/<elemname>?filterByType=nnnn

Get status details of one hardware element (or of all hardware elements if elemname omitted)

Note that the commsOk value is 0 for not connected, 1, for connected and -1 for invalid.

Example request:

hwstatus/status/LeftTwist

Example response:

{"req":"hwstatus/status/LeftTwist","hw":[{"name":"LeftTwist","type":"SmartServo","busName":"I2CA","addr":"0x11","addrValid":1,"IDNo":"1","whoAmI":"","whoAmITypeCode":"FFFFFFFF","SN":"4f7aa220974cadc7","versionStr":"000.000","commsOk":1}],"rslt":"ok"}

hwstatus / minstat

Method: GET

URL pattern:

hwstatus/minstat/<elemname>?filterByType=nnnn

Get minimal status details of one hardware element (or of all hardware elements if elemname omitted)

The mapping from hwstatus is:

name → n, type → t, IDNo → I, whoAmI → w, whoAmITypeCode → W, SN → S, versionStr → v, commsOk → k

Note that the k value is 0 for not connected, 1, for connected and -1 for invalid.

Example request:

hwstatus/minstat/IMU0

Example response:

{"req":"hwstatus/minstat/IMU0","hw":[{"n":"IMU0","t":"IMU","I":19,"w":"KXTJ3","W":"10011057","S":"","v":"0.0.0","k":1}],"rslt":"ok"}

hwstatus / strstat

Method: GET

URL pattern:

hwstatus/strstat/<elemname>?filterByType=nnnn

Get a single string - with fields delimited by | characters - for the hardware status of one element (or all if elemname / filterByType omitted)

The encoded string has the key “a” and is as follows:

If a field is empty then two | symbols will appear together with no space between (see example for SN field which is blank in this case).

If a field contains the | character it will be replaced with the characters “/x7C”

Example request:

hwstatus/strstat/IMU0

Example response:

{"req":"hwstatus/strstat/IMU0","hw":[{"a":{"IMU0|IMU|19|KXTJ3|10011057||0.0.0|1"}}],"rslt":"ok"}

hwstatus / mindata

Method: GET

URL pattern:

hwstatus/mindata/<elemname>?filterByType=nnnn

Get minimal data from hardware element

Example request:

hwstatus/mindata/FuelGauge0

Example response:

{"req":"hwstatus/mindata/FuelGauge0","hw":[{"FuelGauge":{"fresh":1,"atRateMA":0,"atRateTTESecs":99,"voltageV":4.169,"tempC":26.3,"timeToEmptyMins":65535,"timeToFullMins":2655,"availEnergyMWH":2589,"StateOfChgPCOfFull":5}}],"rslt":"ok"}

hwstatus / data

Method: GET

URL pattern:

hwstatus/data/<elemname>?filterByType=nnnn

Get full data from hardware element. Not recommended over BLE as the message may be truncated.

Example request:

hwstatus/data/FuelGauge0

Example response:

{"req":"hwstatus/data/FuelGauge0","hw":[{"FuelGauge":{"fresh":1,"atRateMA":0,"atRateTTESecs":99,"voltageV":4.169,"tempC":26.3,"timeToEmptyMins":65535,"timeToFullMins":2655,"availEnergyMWH":2589,"StateOfChgPCOfFull":5,"nomAvailCapMAH":2648,"fullAvailCapMAH":2682,"remainCapMAH":2508,"fullChgCapMAH":2542,"averageCurrMA":0,"timeToFullMins":2655,"standbyCurrMA":-2,"standbyTTEMins":2542,"maxLoadCurrMA":-5441,"maxLoadTTEMins":2508,"availEnergyMWH":2589,"averagePowerMW":0,"constPowTTEMins":0,"cycleCount":2975,"ctrlStatFlagsHex":224,"flagsHex":88,"flagsStr":"BOARDCAL OVERTMPCHG CHGINHIB XCHGALERT "}}],"rslt":"ok"}

hwstatus / all

Method: GET

URL pattern:

hwstatus/all/<elemname>?filterByType=nnnn

Get all details of one hardware element (note this is like status and data combined). Not recommended over BLE as the message may be truncated.

Example request:

hwstatus/status/LeftTwist

Example response:

{"req":"hwstatus/status/LeftTwist","hw":[{"name":"LeftTwist","type":"SmartServo","busName":"I2CA","addr":"0x11","idx":"1","whoAmI":"","SN":"4f7aa220974cadc7","versionStr":"000.000","commsOk":1}],"rslt":"ok"}

hwstatus / minboth

Method: GET

URL pattern:

hwstatus/minboth/<elemname>?filterByType=nnnn

This combines the minstat and mindata options together

Example request:

hwstatus/minboth/IMU0

Example response:

{"req":"hwstatus/minboth/IMU0","hw":[{"n":"IMU0","t":"IMU","I":19,"w":"KXTJ3","W":"10011057","S":"","v":"0.0.0","k":1,"IMU":{"fresh":1,"x":0.14,"y":-0.07,"z":1.03,"ff":0}}],"rslt":"ok"}

Hardware firmware updates

hwfwupd

Method: GET

URL pattern:

hwfwupd

Get the status of a current firmware update (1st example) or the result of the previous one (2nd example)

“s” is state and can be: “idle”, “scan”, “buspause”, “poweroff”, “poweron”, “comms”, “check”, “done”

“m” is msg and can be: “inProgress“, “failedSendBlock”, “blockRespBad”, “timeOutBlockWrite”, “failedBlockStat“, “ok”, “noElemsMatch”, “noElemsRespond”, “allElemsUpToDate”, “timeOutAwaitingBusPause”, “updateListEmpty”, “timeoutOnRecheck”

“v” is version

“n“ is name of element

“p” is progress (percent)

“i” is incomplete and indicates a previously started firmware update (of hwelem) was not completed

Example request:

hwfwupd

Example response:

{"req":"hwfwupd","st":{"s":"idle","m":"noElemsRespond","v":"0.9.0","n":"","p":100,"i":0},"rslt":"ok"}
OR
{"req":"hwfwupd","st":{"s":"idle","m":"noElemsRespond","v":"0.9.0","n":"","p":100,"i":0},"rslt":"ok"}

hwfwupd / auto

Method: GET

URL pattern:

hwfwupd/auto

Start an automated firmware update. This procedure uses the DeviceTypeID (DTID) of each element to identify a firmware file on the file-system and updates the HWElem using that file (if it exists). See Firmware Update (RIC and HWElems) for more info.

Example request:

hwfwupd/auto

Example response:

{"req":"hwfwupd/auto","rslt":"ok"}

hwfwupd

Method: GET

URL pattern:

hwfwupd//<filename>

Check filename version information

“fileVers” contains the file version from the file header

Example request:

hwfwupd//stm8-servoboard.rfw

Example response:

{"req":"hwfwupd//stm8-servoboard.bin","hwFwStat":{"state":"idle","lastrslt":"","fileVers":"001.002","collated":[]},"rslt":"ok"}
OR
{"req":"hwfwupd//stm8-servoboard.rfw","hwFwStat":{"state":"idle","lastrslt":"","fileVers":"","collated":[]},"rslt":"fail","error":"fileNotFound"}

hwfwupd

Method: GET

URL pattern:

hwfwupd/<elemType>/<fileName>

Update firmware for all elements of type <elemType> with firmware in file <fileName>

The sequence of operations performed is described in HW Element Firmware Update Procedure

During/after an update the hwfwupd api can be used with no parameters to get status.

Example request:

hwfwupd/SmartServo/stm8-servoboard.rfw

Example response:

{"req":"hwfwupd/SmartServo/stm8-servoboard.bin","rslt":"ok"}

hwfwupd

Method: GET

URL pattern:

hwfwupd/<elemType>/<fileName>/<elemName>

Update firmware for element named <elemName> (which must be of type <elemType>)

See the preceding command for more details.

Example request:

hwfwupd/SmartServo/stm8-servoboard.rfw/LeftTwist

Example response:

{"req":"hwfwupd/SmartServo/stm8-servoboard.bin/LeftTwist","rslt":"ok"}

hwfwupd

Method: GET

URL pattern:

hwfwupd/<elemType>//<versionNumber>

Check if the firmware version passed in is later than that on any of the HWElems of type specified.

firmware version is in semver format x.y.z

Example request:

hwfwupd/SmartServo//1.2.3

Example response:

{"req":"hwfwupd/SmartServo//1.2.3",”updateReqd”:1,"rslt":"ok"}

hwfwupd / force

Method: GET

URL pattern:

hwfwupd/<elemType>/<fileName>/<elemNameOrAll>/force

Update regardless of the result of the version comparison between the specified file and the version reported by the element(s)

Example request:

hwfwupd/SmartServo/stm8-servoboard.sfw//force
OR
hwfwupd/SmartServo/stm8-servoboard.sfw/LeftHip/force

Example response:

{"req":"hwfwupd/SmartServo/stm8-servoboard.sfw//force","rslt":"ok"}

System settings

getsettings

Method: GET

URL pattern:

getsettings/<filter>

Get the current settings for the system

The <filter> part is optional and can be all (default), nv (non-volatile), or base.

Example request:

getsettings

Example response:

{"req":"getsettings","sysType":"RICMarty2R2","nv":{},"base":{"SysType":"RICMarty2R2","CmdsAtStart":"","WebUI":"","SysManager":{"monitorPeriodMs":10000,"reportList":["NetMan","BLEMan","RobotCtrl","SysMan","ProtExchg","StatsCB"],...

getsystypes

Method: GET

URL pattern:

getsystypes

Get the types of system that are supported as a list

Example request:

getsystypes

Example response:

{"req":"getsystypes","sysTypes":["RICMarty2R2"],"rslt":"ok"}

getSysTypeConfiguration

Method: GET

URL pattern:

getSysTypeConfiguration/<configname>

Get the JSON configuration for a specific systype

Example request:

getSysTypeConfiguration/RICMarty2

Example response:

{“rslt”:”ok”,"req":getSysTypeConfiguration/RICMarty2","sysType":{"SysType": "RICMarty2","CmdsAtStart": "","WebUI":"","FileManager":{"SPIFFSEnabled": 1,"SPIFFSFormatIfCorrupt": 1," ….

postsettings

Method: POST

URL pattern:

postsettings

Set the JSON configuration for a specific systype

This can only be performed over an HTTP connection

Example request:

postsettings

Example response:

Format is the same as the contents of the "base"/"nv" JSON object returned by getsettings

Indicators and calibration

indicator

Method: GET

URL pattern:

indicator

Set/get (and possibly override normal operation of the) indicators on the RIC to display colours or patterns.

Indicator LEDs (pixels) are numbered 0,1,2 from left to right.

The indicators may have functions defined by the firmware. For indicators that don’t have such functions the set function can be used to set these indicators. For indicators that do have firmware functions is it necessary to override the normal function and this is done by specifying a time (in ms) for which the override is to take place. Overrides are just solid colours (breathe, etc has no effect during override).

“set” is used to set a pattern

“resume” resumes normal operation of indicator LED after an override - if pixIdx isn’t specified then all pixels resume normal operation.

blinkType can be: “off”,”on”,”breathe”

r,g,b are the colour values

rateMs indicates the cycle rate for breathe mode - 1000 means 1 breathe cycle per second

Example request:

indicator/set?pixIdx=1;blinkType=breathe;r=32;g=32;b=0;rateMs=1000
OR
indicator/set?c0=FF0000&c1=00ff00&c2=0000ff&ms=10000
OR
indicator/resume?pixIdx=1
OR
indicator/resume
OR
indicator/get?pixIdx=0
OR
indicator/get

Example response:

{"req":"indicator/set?pixIdx=1;blinkType=breathe;r=32;g=32;b=64;rateMs=1000","rslt":"ok"}
OR
{"req":"indicator/get?pixIdx=0","r":0,"g":0,"b":64,"r2":0,"g2":0,"b2":0,"rOv":0,"gOv":0,"bOv":0,"override":0,"ovLeftMs":0,"blink":"on","cycleMs":1000,"rslt":"ok"}
OR
{"req":"indicator/get","RGBT":["#000040T1","#000000T0","#101010T1"],"rslt":"ok"}
(note that the value T is the blinkType - 0 == off, 1 = solid, 2 = breathe)

calibrate

Method: GET

URL pattern:

calibrate

get persistent calibrated flag

Example request:

calibrate

Example response:

{"req":"calibrate","calDone":0,"rslt":"ok"}

calibrate / setFlag

Method: GET

URL pattern:

calibrate/setFlag/N

set persistent calibrated flag

Example request:

calibrate/setFlag/0
OR
calibrate/setFlag/1

Example response:

{"req":"calibrate/setFlag/0","rslt":"ok"}
{"req":"calibrate/setFlag/1","rslt":"ok"}

calibrate / set

Method: GET

URL pattern:

calibrate/set/<jointName>

sets smart servo calibration

This will set the calibrated zero to be the present position of any motors

Will default to all SmartServo elements, unless a jointName is given

When all is specified or used by default the persistent “calDone” flag returned by calibrate with no params is set to 1

Example request:

calibrate/set
OR
calibrate/set/LeftHip

Example response:

{"req":"calibrate/set/notARealJoint","rslt":"ok"}
Note: currently returns ok no matter what.

calibrate / defaultServoParams

Method: GET

URL pattern:

calibrate/defaultServoParams
[DEPRECATED]

Sends the default servo parameters, as specified in RICSysTypes to the servos. They are stored in non-volatile memory on the servos, so this only needs to happen with fresh servos, or if parameters are changed

Typically this will set:

The direction (i.e. whether clockwise is +ve or -ve)
The position multiplier, a factor that converts the reading from the ADC into degrees
The current limiting thresholds, both instantaneous and sustained
poseable mode aka buzz reduction
PID gain constants - how stiff the motor is

Example request:

calibrate/defaultServoParams

Example response:

Deprecated as of RIC firmware 1.1.8
Removed as of RIC firmware 1.1.10

Hardware element commands

elem / get

Method: GET

URL pattern:

elem/<elemName>/get/<attr>

Get an attribute from a hardware element

Attributes available to be got depend on the element type, for a SmartServo they are:

p: position, calibrated value
s: state byte
c: current reading
t: IDNo
r: raw potentiometer reading, uint16

Result will be ok if value is less than 1 second old, or fail otherwise. Number will be the last available reading (if any)

Note that to get raw potentiometer position from a SmartServo you must first manually read it from the servo using a elem/<jointName>/readrawpos command, since it is not polled

Example request:

elem/LeftHip/get/p

elem / json

Method: GET

URL pattern:

elem/<elemName>/json?cmd=<cmdName>&<name1>=<val1>&<name2>=<val2>…

Perform a cmdJSON command on a hardware element but don’t wait for the command to complete before responding.

cmdJSON commands are defined as a valid JSON string with one top-level element being a name-value pair of “cmd” and a string indicating a command name that the hardware element understands.

The query string arguments are formed into additional JSON name-value pairs and also included in the JSON passed to the hardware element.

The behaviour of the hwElem is defined by that element. For HWElemAddOns:

cmd=raw allows for direct connection to an add-on (both Robotical-Standard-Add-Ons and ordinary I2C devices). The response DOES NOT carry data read from the HWElem - this is communicated in a separate REPORT message which is sent on all attached interfaces (see msgKey below). Other json name-values for raw:
- hexWr=AABBCCDD - the data represented by the hex values AABBCCDD is written to the HWElem
- numToRd=N - N bytes of data are read from the HWElem
- msgKey=1234 - this value is stored and is returned in a separate REPORT message

Example request:

elem/AddOn_I2CA_60/json?cmd=raw&hexWr=55AA220554&numToRd=5&msgKey=1234

Example response:

{"req":"elem/AddOn_I2CA_60/json?cmd=raw&hexWr=55AA220554&numToRd=5&msgKey=1234","rslt":"ok"}
Example REPORT message - sent separately:

elem

Method: GET

URL pattern:

elem/<elemName>/<cmdName>/<attrVal>

Perform a command on a hardware element

The commands below marked with ** in their descriptions have the following options for <elemName>:

elemName can be “all” which causes the command to be performed on all hardware elements (of any type)
elemName can be “allELEMTYPE” where ELEMTYPE is a type of hardware element such as SmartServo

Example request:

elem/LeftHip/buzz/1
elem/all/buzz/1
elem/allSmartServo/buzz/1

elem / buzz

Method: GET

URL pattern:

elem/<elemName>/buzz/<val>

** Set “buzz reduction” functionality on a servo.

This will make a servo adjust its target position when it is not busy to avoid any load

Example request:

elem/LeftHip/buzz/1
OR
elem/LeftHip/buzz/0

Example response:

{"req":"elem/LeftHip/buzz/1","rslt":"ok"}

elem / inst

Method: GET

URL pattern:

elem/<jointName>/inst/<val>

Set instantaneous current limit on a servo

Example request:

elem/LeftHip/inst/80

Example response:

{"req":"elem/LeftHip/inst/80","rslt":"ok"}

elem / sus

Method: GET

URL pattern:

elem/<jointName>/sus/<val>

Set sustained current limit on a servo

Example request:

elem/LeftHip/sus/80

Example response:

{"req":"elem/LeftHip/buzz/80","rslt":"ok"}

elem / posmult

Method: GET

URL pattern:

elem/<jointName>/posmult/<val>

Set position multiplier, to calibrate a servo into degrees.

Internally, this number will be divided by 1000, so a default of 700 for the A0090 corresponds to a multiplier of 0.7

Example request:

elem/Lefthip/posmult/700

Example response:

{"req":"elem/LeftHip/posmult/700","rslt":"ok"}

elem / kp

Method: GET

URL pattern:

elem/<jointName>/kp/<val>

Set Kp, the proportional gain of the PID controller

Internally this number is divided by 1000. A default of 1,000 gives a strong response

Example request:

elem/LeftHip/kp/1000

Example response:

{"req":"elem/LeftHip/kp/1000","rslt":"ok"}

elem / ki

Method: GET

URL pattern:

elem/<jointName>/ki/<val>

Set Ki, the integral gain of the PID controller

Internally, this number is divided by 1,000,000. Default is 0 but 100 works well

Example request:

elem/LeftHip/ki/100

Example response:

{"req":"elem/LeftHip/ki/100","rslt":"ok"}

elem / kd

Method: GET

URL pattern:

elem/<jointName>/kd/<val>

Set Kd, the derivative gain of the PID controller

Internally, this number is divided by 1000

Example request:

elem/LeftHip/kd/1000

Example response:

{"req":"elem/LeftHip/kd/1000","rslt":"ok"}

elem / saveparams

Method: GET

URL pattern:

elem/<jointName>/saveparams

STM32 servo boards only

Save any parameter changes to non-volatile storage. This only needs to be done for the base elements, i.e. LeftHip, RightHip, LeftArm

Example request:

elem/LeftHip/saveparams

elem / readrawpos

Method: GET

URL pattern:

elem/<jointName>/readrawpos

Read the raw potentiometer value from a servo.

This only adds the request to the i2c bus queue, it will not return the result. The result can be fetched using the get command above

Example request:

elem/LeftArm/readrawpos

elem / log

Method: GET

URL pattern:

elem/<jointName>/log/<timeMs>

Start logging data from a servo, for timeMs ms. Results can be read using the getjson/servolog command

Example request:

elem/LeftHip/log/5000

elem / getjson

Method: GET

URL pattern:

elem/<jointName>/getjson/servolog

Get servolog data from specified joint. A log command must have been given previously

Example request:

elem/Lefthip/getjson/servolog

Add-on configuration

addon / list

Method: GET

URL pattern:

addon/list

List add-on configurations (from non-volatile storage - not the connected add-ons).

Example request:

addon/list

Example response:

{"req":"addon/list","addons":[{"name":"banana","SN":"0102030405060708","poll":"","pollRd":10,"pollHz":1.0}],"rslt":"ok"}

addon / get

Method: GET

URL pattern:

addon/get

Get a specific add-on by serial number

Example request:

addon/get?SN=0102030405060708

Example response:

{"req":"addon/get?SN=0102030405060708","addon":{"name":"banana1","SN":"0102030405060708","poll":"","pollRd":10,"pollHz":1.0},"rslt":"ok"}

addon / set

Method: GET

URL pattern:

addon/set

Set add-on values for a specific serial number (using the query string format)

Example request:

addon/set?SN=0102030405060708&name=elephant&pollRd=8

Example response:

{"req":"addon/set?SN=0102030405060708&name=elephant&pollRd=8","rslt":"ok"}

addon / del

Method: GET

URL pattern:

addon/del

Delete add-on with specified serial number.

Note that this will delete the entry in non-volatile storage but won’t immediately change the reported name of an add-on with this serial-number although that will happen after a restart.

Example request:

addon/del?SN=0102030405060708

Example response:

{"req":"addon/del?SN=0102030405060708","rslt":"ok"}

addon / clear

Method: GET

URL pattern:

addon/clear

Clear list of add-ons

Example request:

addon/clear

Example response:

{"req":"addon/clear","rslt":"ok"}

Diagnostics, subscriptions and WiFi control

sysman

Method: GET

URL pattern:

sysman

Set the SysMan parameters.

The rate at which SysMan diagnostics are reported is controlled by the interval parameter. This is in seconds.

The SysModules which are reported on is controlled by the report parameter. This must be a list of SysMod names with square brackets at the start and end of the list and each module name enclosed in double quotes. Example SysMod names are:

NetMan
BLEMan
SysMan

The size of the rx and tx serial buffers used by SysMan (which includes the over-ascii protocol if USB serial is being used to control RIC) can be set using:

rxBuf
txBuf

The serial baud rate can be set using the baudRate parameter but it should be noted that this will change all communication and currently isn’t supported in SerialMonitor or martypy so use with caution.

Example request:

sysman?interval=1.5&report=["NetMan","BLEMan","SysMan"]
OR
sysman?rxBuf=10240&txBuf=1024

Example response:

{"req":"sysman?interval=1.5&report=[NetMan,BLEMan,SysMan]","rslt":"ok"}

subscription

Method: GET

URL pattern:

subscription

Setup subscriptions to information published by RIC.

The following published information is available (selected by the “name” field in the “pubRecs” array):

“MultiStatus“ - information from the accelerometer, smart servos and general robot status
“PowerStatus” - information from the Fuel-Gauge and power controller
“AddOnStatus” - information about connected add-ons

To enable subscriptions for a specific type of information use the “rateHz” field to specify a non-zero publish rate in Hz.

To disable subscriptions specify a “rateHz” value of zero for the specific type of information.

Note that subscriptions operate “by channel” which means that subscriptions on a BLE connection can be different than on a WiFi connection.

Note that subscriptions on BLE and to the Micropython subsystem are turned on by default but all other subscriptions must be turned on for the specific channel.

Note that separate REST API commands must be used for each type of information. There is a way to set multiple subscriptions at once using the CommandFrame format CommandFrame format messages

Example request:

subscription?action=update&name=MultiStatus&rateHz=10.0

Example response:

{'req': 'subscription', 'rslt': 'ok'}
The example sets the subscription rates on the current channel to 10Hz for MultiStatus

wifipause

Method: GET

URL pattern:

wifipause

Pause/Resume WiFi operation to give precedence to BLE

wifi/pause

wifi/resume

Example request:

wifipause/pause
wifipause/resume

Example response:

{"req":"wifipause/pause","rslt":"ok"}
{"req":"wifipause/resume","rslt":"ok"}

wifiscan

Method: GET

URL pattern:

wifiscan

Start or get the results of a WiFi scanning operation.

wifiscan/start

wifiscan/results

Example request:

wifiscan/start
wifiscan/results

Example response:

{"req":"wifiscan/start","rslt":"ok"}
{"req":"wifiscan/results","wifi":[{"ssid":"rd01","rssi":-66,"ch1":6,"ch2":0,"auth":"WPA2_PSK","bssid":"aa:aa:9a:17:89:bb","pair":"CCMP","group":"CCMP"},{"ssid":"rd01","rssi":-73,"ch1":11,"ch2":0,"auth":"WPA2_PSK","bssid":"aa:aa:da:11:eb:3b","pair":"CCMP","group":"CCMP"},{"ssid":"rd01","rssi":-76,"ch1":1,"ch2":0,"auth":"WPA2_PSK","bssid":"aa:aa:da:11:ea:92","pair":"CCMP","group":"CCMP"},{"ssid":"ChromecastXXXv","rssi":-83,"ch1":11,"ch2":0,"auth":"OPEN","bssid":"fa:aa:aa:58:d2:d9","pair":"NONE","group":"NONE"},{"ssid":"rd01","rssi":-83,"ch1":11,"ch2":0,"auth":"WPA2_PSK","bssid":"aa:aa:da:11:ef:7d","pair":"CCMP","group":"CCMP"},{"ssid":"BT-WPL4QG","rssi":-89,"ch1":1,"ch2":0,"auth":"WPA2_PSK","bssid":"aa:aa:29:17:11:d2","pair":"CCMP","group":"CCMP"},{"ssid":"BTWifi-A9H","rssi":-90,"ch1":6,"ch2":0,"auth":"WPA_WPA2_PSK","bssid":"aa:aa:6d:61:5d:b8","pair":"TKIP_CCMP","group":"TKIP"},{"ssid":"093-alt","rssi":-92,"ch1":6,"ch2":0,"auth":"WPA2_PSK","bssid":"aa:aa:c1:f2:89:be","pair":"TKIP_CCMP","group":"TKIP"},{"ssid":"NM83242","rssi":-93,"ch1":1,"ch2":0,"auth":"WPA_WPA2_PSK","bssid":"aa:aa:43:54:bd:39","pair":"TKIP_CCMP","group":"TKIP"}],"rslt":"ok"}

LED commands

led / setleds

URL pattern:

led/<nameOrType>/setleds/<[RGB]>

Set multiple sequential leds starting from the first led

nameOrType will be matched against elemName and whoami string

Example request:

led/LeftLedEye/setleds/FFFFFF00FF00

led / setall

URL pattern:

led/[nameOrType]/setall/<RGB>

Set all LEDs to the same color

Set all LEDs of the left eye to the same color

Example request:

led/all/setall/880088
led/LeftLedEye/setall/FFFFFF

led / setled

URL pattern:

led/<nameOrType/setled/<ledID>/<RGB>

Set a single led to a color

Example request:

led/RightLedEye/setled/1/004508

led / pattern

URL pattern:

led/[nameOrType]/pattern/[patternName]

Activate a named pattern on both eyes.

Pattern names can be retrieved using the listPatterns command

Optionally the period of the pattern can be set in ms (i.e. the time to complete one full cycle) [NOT YET IMPLEMENTED]

Example request:

led/LEDeye/pattern/rainbow
led/LEDeye/pattern/show-off?period=1000

led / color

URL pattern:

led/<nameOrType>/color/<RGBorPersist>

Sets all leds to a color

Set leds 2 and 10 to green, and all others to red

Sets led 5 to blue, and leave all the others as they are

Example request:

led/LEDeye/color/FF0000
led/LEDeye/color/FF0000?2=00FF00&10=00FF00
led/LEDeye/color/persist?5=0000FF

led / region

URL pattern:

led/<nameOrType>/region/<regionID>/<RGB>

Set region (0,1,2) to a specified color.

Region definitions can be seen on the user guides site

Example request:

led/LEDfoot/region/1/001122

led / listPatterns

URL pattern:

led/<nameOrType>/listPatterns

Returns a list of available patterns

Currently ignores nameOrType parameter (v1.2.7), but will later return a list specific to that element or group. If no nameOrType is given, or it’s set to all, it will return a list of all available patterns - not all patterns may be available for each addon

Example request:

led/LEDeye/listpatterns

Example response:

{"req":"led/LEDeye/listPatterns","patterns":["show-off","rainbow"],"rslt":"ok"}

led / off

URL pattern:

led/[nameOrType]/off

shorthand for setall/000000

Turn all LEDs off

Example request:

led/LeftLEDEye/off

Table of Contents

Request format

System, network and power commands

v

friendlyname

w

wc

reset

serialno

hwrevno

pwrctrl

Motion, programs and audio

traj

pyrun

pystop

pystatus

audio / vol

audio / pause

robot

Files

filerun

filelist

fileread

filedelete

fileupload

System module information

sysmodinfo

sysmoddebug

Hardware status

hwstatus

hwstatus / name

hwstatus / status

hwstatus / minstat

hwstatus / strstat

hwstatus / mindata

hwstatus / data

hwstatus / all

hwstatus / minboth

Hardware firmware updates

hwfwupd

hwfwupd / auto

hwfwupd

hwfwupd

hwfwupd

hwfwupd

hwfwupd / force

System settings

getsettings

getsystypes

getSysTypeConfiguration

postsettings

Indicators and calibration

indicator

calibrate

calibrate / setFlag

calibrate / set

calibrate / defaultServoParams

Hardware element commands

elem / get

elem / json

elem

elem / buzz

elem / inst

elem / sus

elem / posmult

elem / kp

elem / ki

elem / kd

elem / saveparams

elem / readrawpos

elem / log

elem / getjson

Add-on configuration

addon / list

addon / get

addon / set

addon / del

addon / clear

Diagnostics, subscriptions and WiFi control

sysman