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 |
| |
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/ |
OR | |
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 |
| |
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 |
| |
reset | GET | Schedule a reset in around 1 second | reset |
| |
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 |
| |
hwrevno | GET | Get RIC hardware revision number The HW revision number is a positive integer | hwrevno |
| |
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 |
| |
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 |
| |
pyrun | GET | Run a micropython program The procCtrl parameters are optional and indicate:
| pyrun/screenfree.py OR pyrun/screenfree.py?procCtrl=noclear+nostop |
| |
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 |
| |
pystatus | GET | Get the name of the currently running micropython program (or blank if nothing running) | pystatus |
| |
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 |
| |
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 |
| |
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 |
| |
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 |
| |
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 |
| |
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 |
OR
| |
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 |
| ||
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 |
OR
OR
| |
sysmoddebug | GET | Get debug info about a SysMod by name, SysMod names that are valid include: SysMan | sysmoddebug/RobotCtrl |
| |
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
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:
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 |
| |
hwstatus/name?filterByType=nnnn | GET | Get the names of all hardware elements | hwstatus/name |
| |
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 |
| |
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 |
| |
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 |
| |
hwstatus/mindata/<elemname>?filterByType=nnnn | GET | Get minimal data from hardware element | hwstatus/mindata/FuelGauge0 |
| |
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 |
| |
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 |
| |
hwstatus/minboth/<elemname>?filterByType=nnnn | GET | This combines the minstat and mindata options together | hwstatus/minboth/IMU0 |
| |
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 |
OR
| |
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 |
| |
hwfwupd//<filename> | GET | Check filename version information “fileVers” contains the file version from the file header | hwfwupd//stm8-servoboard.rfw |
OR
| |
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 |
| |
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 |
| |
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 |
| |
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 |
| |
getsettings/<filter> | GET | Get the current settings for the system The <filter> part is optional and can be | getsettings |
| |
getsystypes | GET | Get the types of system that are supported as a list | getsystypes |
| |
getSysTypeConfiguration/<configname> | GET | Get the JSON configuration for a specific systype | getSysTypeConfiguration/RICMarty2 |
| |
postsettings | POST | Set the JSON configuration for a specific systype This can only be performed over an HTTP connection | postsettings |
| |
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 OR indicator/resume?pixIdx=1 OR indicator/resume OR indicator/get?pixIdx=0 OR indicator/get |
OR
OR
(note that the value T is the blinkType - 0 == off, 1 = solid, 2 = breathe) | |
calibrate | GET | get persistent calibrated flag | calibrate |
| |
calibrate/setFlag/N | GET | set persistent calibrated flag | calibrate/setFlag/0 OR calibrate/setFlag/1 |
| |
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 |
| |
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:
| 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:
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:
| 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>:
| 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 |
| |
elem/<jointName>/inst/<val> | GET | Set instantaneous current limit on a servo | elem/LeftHip/inst/80 |
| |
elem/<jointName>/sus/<val> | GET | Set sustained current limit on a servo | elem/LeftHip/sus/80 |
| |
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 |
| |
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 |
| |
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 |
| |
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 |
| |
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 | elem/Lefthip/getjson/servolog | ||
addon/list | GET | List add-on configurations (from non-volatile storage - not the connected add-ons). | addon/list |
| |
addon/get | GET | Get a specific add-on by serial number | addon/get?SN=0102030405060708 |
| |
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 |
| |
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 |
| |
addon/clear | GET | Clear list of add-ons | addon/clear |
| |
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:
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:
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 |
| |
subscription | GET | Setup subscriptions to information published by RIC. The following pubished information is available (selected by the “name” field in the “pubRecs” array):
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 |
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/[nameOrType]/setall/<RGB> | Set all LEDs to the same color Set all LEDs of the left eye to the same color |
| |||
led/<nameOrType/setled/<ledID>/<RGB> | Set a single led to a color |
| |||
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/<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/<nameOrType>/region/<regionID>/<RGB> | Set region (0,1,2) to a specified color. Region definitions can be seen on the user guides site |
| |||
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/[nameOrType]/off | shorthand for setall/000000 Turn all LEDs off |
|