====== REST API ======

 

The REST API is based on conventional REST operations (GET and POST only).

Note that to use an API command over WiFi HTTP the URL needs to start with:

http://<ipaddrorname>/api/

so for example:
http://mymarty/api/v

Over other interfaces (such as BLE and CommandSerial) the command must be wrapped in a RICFrame or RICSerial message and is not prefixed with api but must have a leading forward slash, for example:

/v

The commands implemented include:

URL

Verb

Description

e.g. req

e.g. resp

v

GET

Get the system name and version of RIC

v

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

friendlyname

GET

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

friendlyname

OR

friendlyname/My Marty

OR

friendlyname/

{"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/<ssid>/<password>

OR

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

GET

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

w/myssid/mypassword/marty

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

wc/<norestart>

GET

Clear WiFi credentials and disconnect WiFi

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

wc

OR

wc/norestart

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

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

reset

GET

Schedule a reset in around 1 second

reset

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

serialno

GET

Set/get serial number

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

Setting requires the additional value “RoboticalMagic”

serialno

or

serialno/01234567890ABCDEF0123456789ABCDEF/RoboticalMagic

{"req":"serialno","SerialNo":"0123456789abcdef0123456789abcdef","rslt":"ok"}

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

hwrevno

GET

Get RIC hardware revision number

The HW revision number is a positive integer

hwrevno

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

pwrctrl

GET

Power control of the robot

setChgEn will only have an affect 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)

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

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

traj

GET

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.

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

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

pyrun

GET

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.

pyrun/screenfree.py

OR

pyrun/screenfree.py?procCtrl=noclear+nostop

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

pystop

GET

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

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

The procCtrl parameter is described in pyrun command

pystop

OR

pystop?procCtrl=noclear+nostop

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

pystatus

GET

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

pystatus

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

audio/vol

audio/vol/vPC

GET

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

audio/vol

audio/vol/60

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

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

audio/pause

audio/resume

audio/stop

GET

pause/resume/stop audio playback.

audio/pause

audio/resume

audio/stop

robot

GET

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

robot/stop

robot/stopAfterMove

robot/panic

robot/pause

robot/resume

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

filerun/<fileName>

OR

filerun/sd~<fileName>

OR

filerun/local~<fileName>

GET

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~.

filerun/confused.raw

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

filelist

OR

filelist/local

OR

filelist/sd

GET

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

filelist

{"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/local/<fileName>

OR

fileread/sd/<fileName>

GET

Read a text file from file system

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

fileread/local/home.css

… the text content of the file …

filedelete/local/<fileName>

OR

filedelete/sd/<fileName>

GET

Delete a file from file system

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

filedelete/local/test.txt

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

OR

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

fileupload

POST

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

Uses the regular HTTP file upload protocol

sysmodinfo

GET

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

NetMan

BLEMan

SysMan

sysmodinfo/NetMan

sysmodinfo/BLEMan

{“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

GET

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

SysMan

sysmoddebug/RobotCtrl

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

hwstatus?filterByType=nnnn

GET

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

hwstatus

{
    "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?filterByType=nnnn

GET

Get the names of all hardware elements

hwstatus/name

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

hwstatus/status/<elemname>?filterByType=nnnn

GET

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.

hwstatus/status/LeftTwist

{"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/<elemname>?filterByType=nnnn

GET

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.

hwstatus/minstat/IMU0

{"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/<elemname>?filterByType=nnnn

GET

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:

name | type | IDNo | whoAmI | whoAmITypeCode | SN | versionStr | commsOk

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”

hwstatus/strstat/IMU0

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

hwstatus/mindata/<elemname>?filterByType=nnnn

GET

Get minimal data from hardware element

hwstatus/mindata/FuelGauge0

{"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/<elemname>?filterByType=nnnn

GET

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

hwstatus/data/FuelGauge0

{"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/<elemname>?filterByType=nnnn

GET

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.

hwstatus/status/LeftTwist

{"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/<elemname>?filterByType=nnnn

GET

This combines the minstat and mindata options together

hwstatus/minboth/IMU0

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

hwfwupd

GET

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

hwfwupd

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

GET

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.

hwfwupd/auto

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

hwfwupd//<filename>

GET

Check filename version information

“fileVers” contains the file version from the file header

hwfwupd//stm8-servoboard.rfw

{"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/<elemType>/<fileName>

GET

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.

hwfwupd/SmartServo/stm8-servoboard.rfw

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

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

GET

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

See the row above for more details.

hwfwupd/SmartServo/stm8-servoboard.rfw/LeftTwist

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

hwfwupd/<elemType>//<versionNumber>

GET

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

hwfwupd/SmartServo//1.2.3

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

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

GET

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

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

OR

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

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

getsettings/<filter>

GET

Get the current settings for the system

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

getsettings

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

getsystypes

GET

Get the types of system that are supported as a list

getsystypes

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

getSysTypeConfiguration/<configname>

GET

Get the JSON configuration for a specific systype

getSysTypeConfiguration/RICMarty2

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

postsettings

POST

Set the JSON configuration for a specific systype

This can only be performed over an HTTP connection

postsettings

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

indicator

GET

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

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

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

GET

get persistent calibrated flag

calibrate

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

calibrate/setFlag/N

GET

set persistent calibrated flag

calibrate/setFlag/0

OR

calibrate/setFlag/1

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

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

calibrate/set/<jointName>

GET

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

calibrate/set

OR

calibrate/set/LeftHip

{"req":"calibrate/set/notARealJoint","rslt":"ok"}

Note: currently returns ok no matter what.

calibrate/defaultServoParams

[DEPRECATED]

GET

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

calibrate/defaultServoParams

Deprecated as of RIC firmware 1.1.8

Removed as of RIC firmware 1.1.10

elem/<elemName>/get/<attr>

GET

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

elem/LeftHip/get/p

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

GET

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

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

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

Example REPORT message - sent separately:

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

GET

Perform a command on a hardware element

The commands in the table following this marked with a ** in this column 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

elem/LeftHip/buzz/1

elem/all/buzz/1

elem/allSmartServo/buzz/1

elem/<elemName>/buzz/<val>

GET

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

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

elem/LeftHip/buzz/1

OR

elem/LeftHip/buzz/0

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

elem/<jointName>/inst/<val>

GET

Set instantaneous current limit on a servo

elem/LeftHip/inst/80

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

elem/<jointName>/sus/<val>

GET

Set sustained current limit on a servo

elem/LeftHip/sus/80

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

elem/<jointName>/posmult/<val>

GET

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

elem/Lefthip/posmult/700

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

elem/<jointName>/kp/<val>

GET

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

elem/LeftHip/kp/1000

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

elem/<jointName>/ki/<val>

GET

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

elem/LeftHip/ki/100

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

elem/<jointName>/kd/<val>

GET

Set Kd, the derivative gain of the PID controller

Internally, this number is divided by 1000

elem/LeftHip/kd/1000

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

elem/<jointName>/saveparams

GET

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

elem/LeftHip/saveparams

elem/<jointName>/readrawpos

GET

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

elem/LeftArm/readrawpos

elem/<jointName>/log/<timeMs>

GET

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

elem/LeftHip/log/5000

elem/<jointName>/getjson/servolog

GET

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

elem/Lefthip/getjson/servolog

addon/list

GET

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

addon/list

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

addon/get

GET

Get a specific add-on by serial number

addon/get?SN=0102030405060708

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

addon/set

GET

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

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

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

addon/del

GET

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.

addon/del?SN=0102030405060708

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

addon/clear

GET

Clear list of add-ons

addon/clear

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

sysman

GET

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.

sysman?interval=1.5&report=["NetMan","BLEMan","SysMan"]

OR

sysman?rxBuf=10240&txBuf=1024

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

subscription

GET

Setup subscriptions to information published by RIC.

The following pubished 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

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

{'req': 'subscription', 'rslt': 'ok'}

The example sets the subscription rates on the current channel to 10Hz for MultiStatus

wifipause

GET

Pause/Resume WiFi operation to give precedence to BLE

wifi/pause

wifi/resume

wifipause/pause

wifipause/resume

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

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

wifiscan

GET

Start or get the results of a WiFi scanning operation.

wifiscan/start

wifiscan/results

wifiscan/start

wifiscan/results

{"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/<nameOrType>/setleds/<[RGB]>

Set multiple sequential leds starting from the first led

nameOrType will be matched agains elemName and whoami string

led/LeftLedEye/setleds/FFFFFF00FF00

led/[nameOrType]/setall/<RGB>

Set all LEDs to the same color

Set all LEDs of the left eye to the same color

led/all/setall/880088

led/LeftLedEye/setall/FFFFFF

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

Set a single led to a color

led/RightLedEye/setled/1/004508

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]

led/LEDeye/pattern/rainbow

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

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

led/LEDeye/color/FF0000

led/LEDeye/color/FF0000?2=00FF00&10=00FF00

led/LEDeye/color/persist?5=0000FF

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

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

Region definitions can be seen on the user guides site

led/LEDfoot/region/1/001122

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

led/LEDeye/listpatterns

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

led/[nameOrType]/off

shorthand for setall/000000

Turn all LEDs off

led/LeftLEDEye/off