API documentation
Webinterface
General concept
HTTP requests:
GET requests to get information or config, no parameters passed.
POST requests to set config with params passed as JSON.
POST requests for commands, with params passed as JSON.
Requests return a "400 Bad Request" for bad requests (e.g., illegal path, bad parameters) or "500 Internal Server Error" for very bad requests (e.g., malformed headers).
All requests to valid endpoints return a JSON:
CODE{ "_ok": true, "_message:": "...", // And additional fields depending on the request... }
_ok
indicates success (true) or failure (false) executing the request._message
may be empty or contain a message that could be displayed to the user.A few requests return different data (for example, /api/v2/camera/stream, /api/v2/camera/calib_dl and /api/v2/log/dl).
Configuration set requests that do not change the configuration are valid. For example, setting fusion autostart to disabled while it already is disabled, is a valid request and results in _ok = true.
Do not call APIs too often, as it increases the system load. Query at most at 1 Hz.
API responsiveness monitoring
/api/v2/api_up (GET) -- Check if API is up
Reponse
CODE{ "_ok": true, "_message": "..." // always true, unless server is broken }
Duration: "instant"
Example
CODEcurl -i http://10.0.2.1/api/v2/api_up
System info
/api/v2/sys/load (GET) -- System load
Reponse
CODE{ "_ok": true, "_message": "...", "system_load": 1.81 // System load [-] }
Duration: "instant"
Example
CODEcurl -i http://10.0.2.1/api/v2/sys/load
/api/v2/sys/cpu (GET) -- CPU load and temperature
Response
CODE{ "_ok": true, "_message": "...", "cpu_load": 28, // [%], 1s average "cpu_temp": 59 // [C] }
Duration: 1 second, do not call more often than every couple of seconds
Example
CODEcurl -i http://10.0.2.1/api/v2/sys/cpu
/api/v2/sys/uptime (GET) -- System uptime
Response
CODE{ "_ok": true, "_message": "...", "uptime": 82306 // [s] }
Duration: "instant"
Example
CODEcurl -i http://10.0.2.1/api/v2/sys/uptime
/api/v2/sys/load_cpu_uptime (GET) -- All of the above
Response
CODE{ "_ok": true, "_message": "...", "cpu_load": 29, "cpu_temp": 59, "system_load": 2.09, "uptime": 82339 }
Duration: 1 second, do not call more often than every couple of seconds
Example
CODEcurl -i http://10.0.2.1/api/v2/sys/load_cpu_uptime
/api/v2/sys/info (GET) -- System information (versions, etc.) [strings]
Response
CODE{ "_ok": true, "_message": "...", "product": "vision", "hardware": "nav-vr2", "release_tag": "fp_release_1.2.3_123", // deprecated, use sw_ver instead "sw_ver": "fp_release_1.2.3_123", // Since software 2.85.3 "hw_ver": "1.2a", "hostname": "fp-6d9d18", "uid": "fp-6d9d18", }
Duration: "instant"
Example
CODEcurl -i http://10.0.2.1/api/v2/sys/info
/api/v2/sys/timesync (GET) -- Get system time sync status [strings]
Response
CODE{ "_ok": true, "_message": "...", "status": "syncgnss", // "syncgnss", "syncntp", "nosync", "error" "message": "Time synced to GNSS", // A message suitable to display to the user }
Duration: This request may take up to two seconds to complete. Do not call this more often than every few seconds.
Example
CODEcurl -i http://10.0.2.1/api/v2/sys/timesync
Software Update
To update the software via command line, see this guide: Updating software version | Installing-the-software-update-image-(.swu-file)-via-command:
CAN
/api/v2/can/if_get (GET) -- Get CAN interface saved and active config
Response
CODE{ "_ok": true, "_message": "...", // Saved configuration, will apply on next boot "config_enabled": true, "config_bitrate": 500000, "config_dbitrate": 500000, // Currently active (used) configuration "active_enabled": true, "active_bitrate": 500000, // or 0 if active_enabled=false "active_dbitrate": 500000 // or 0 if active_enabled=false }
Duration: "instant"
Example
CODEcurl -i http://10.0.2.1/api/v2/can/if_get
/api/v2/can/if_set (POST) -- Set CAN interface saved config
Request
CODE{ "config_enabled": false, // true, false "config_bitrate": 125000, // 10000, 20000, 50000, 125000, 250000, 500000, 800000, 1000000 "config_dbitrate": 250000 // 10000, 20000, 50000, 125000, 250000, 500000, 800000, 1000000 }
Response
CODE{ "_ok": true, "_message": "...", // _ok = false on failure // Saved config, becomes active on reboot "config_enabled": false, "config_bitrate": 125000, "config_dbitrate": 250000, // Currently active config "active_enabled": true, "active_bitrate": 500000, "active_dbitrate": 500000 }
Duration: "instant"
Example
CODEcurl -i http://10.0.2.1/api/v2/can/if_set -X POST -H "Content-Type: application/json" \ -d '{"config_bitrate":125000,"config_dbitrate":250000,"config_enabled": false}'
/api/v2/can/if_reset (POST) -- Reset CAN interface saved config to default
Request
CODE{ "reset": "default" }
Duration: "instant"
Response
CODE{ "_ok": true, "_message": "...", // Saved config, becomes active on reboot "config_enabled": true, "config_bitrate": 500000, "config_dbitrate": 500000, // Currently active config "active_enabled": true, "active_bitrate": 125000, "active_dbitrate": 125000 }
Example
CODEcurl -i http://10.0.2.1/api/v2/can/if_reset -X POST -H "Content-Type: application/json" \ -d '{"reset":"default"}'
GNSS
/api/v2/gnss/rtk_status (GET) -- Get RTK corrections stream status
Response
CODE{ "_ok": true, "_message": "...", "status": "connected", // "connected", "connecting", "warning", "error" "message": "connected to ntrip.fixposition.com/FP01" // A message suitable to display to the user }
Duration: "instant"
Example
CODEcurl -i http://10.0.2.1/api/v2/gnss/rtk_status
/api/v2/gnss/rtk_get (GET) -- Get RTK correction stream parameters
Response
CODE{ "_ok": true, "_message": "...", "ntrip_user": "user", "ntrip_pass": "pass", "ntrip_host": "host", "ntrip_port": 2101, "ntrip_mount": "mount", "gga_mode": "auto", // "auto" or "manual" "gga_lat": 0.0, "gga_lon": 0.0, "gga_height": 0.0, "source": "serial", // "ntrip" or "serial" }
Duration: "instant"
Example
CODEcurl -i http://10.0.2.1/api/v2/gnss/rtk_get
/api/v2/gnss/rtk_set (POST) -- Set RTK correction stream parameters
Request
CODE{ "ntrip_user": "lukas", // at least one char "ntrip_pass": "meier", // at least one char "ntrip_host": "ntrip.fixposition.com", // at least one char "ntrip_port": 1234, // 1..65535 "ntrip_mount": "FOO", // at least one char "gga_mode": "manual", // "auto" or "serial" "gga_lat": 47.5, // -90..90 "gga_lon": 8.3, // -180..180 "gga_height": 400, // -1000..10000 "source": "ntrip", // "ntrip" or "serial" }
Duration: "instant"
Response
CODE{ "_ok": true, "_message": "...", "ntrip_user": "lukas", "ntrip_pass": "pass", "ntrip_host": "ntrip.fixposition.com", "ntrip_port": 1234, "ntrip_mount": "FOO", "gga_mode": "manual", "gga_lat": 47.5, "gga_lon": 8.3, "gga_height": 400, "source": "ntrip", }
Example
CODEcurl -i http://10.0.2.1/api/v2/gnss/rtk_set -X POST -H "Content-Type: application/json" \ -d '{"ntrip_user":"lukas","ntrip_pass":"meier","ntrip_host":"ntrip.fixposition.com","ntrip_port":1234,"ntrip_mount":"FOO","gga_mode":"manual","gga_lat":47.5,"gga_lon":8.3,"gga_height":400,"source":"ntrip"}'
/api/v2/gnss/rtk_reset (POST) -- Reset RTK correction stream parameters to default
Request
CODE{ "reset": "default" }
Duration: "instant"
Response
CODE{ "_ok": true, "_message": "...", "ntrip_user": "user", "ntrip_pass": "pass", "ntrip_host": "host", "ntrip_port": 2101, "ntrip_mount": "mount", "gga_mode": "auto", "gga_lat": 0.0, "gga_lon": 0.0, "gga_height": 0, "source": "serial", }
Example
CODEcurl -i http://10.0.2.1/api/v2/gnss/rtk_reset -X POST -H "Content-Type: application/json" \ -d '{"reset":"default"}'
/api/v2/gnss/rx_reset (POST) -- Reset GNSS receiver
Request
CODE{ "gnss": 1, // 1 or 2 "type": "hot" // "hot", "warm" or "cold" }
Response
CODE{ "_ok": true, "_message": "...", }
Duration: "instant" (the actual receiver reset can take a second or so)
Example
CODEcurl -i http://10.0.2.1/api/v2/gnss/rx_reset -X POST -H "Content-Type: application/json" \ -d '{"gnss":1,"type":"hot"}'
Map
/api/v2/map/token_get (POST) -- Get map access token
Request
CODE{ "which": "mapbox" }
Response
CODE{ "_ok": true, "_message": "...", "token": "builtinnotsecrettoken", "is_user": false, }
Duration: "instant"
Example
CODEcurl -i http://10.0.2.1/api/v2/map/token_get -X POST -H "Content-Type: application/json" \ -d '{"which":"mapbox"}'
/api/v2/map/token_set (POST) -- Set map access token
Request
CODE{ "which": "mapbox", "token": "verysecretnot" }
Response
CODE{ "_ok": true, "_message": "...", "token": "verysecretnot", "is_user": true, }
Duration: "instant"
Example
CODEcurl -i http://10.0.2.1/api/v2/map/token_set -X POST -H "Content-Type: application/json" \ -d '{"which":"mapbox","token":"verysecretnot"}'
/api/v2/map/token_reset (POST) -- Reset map access token to default
Request
CODE{ "reset": "default", "which": "mapbox" }
Response
CODE{ "_ok": true, "_message": "...", "token": "builtinnotsecrettoken", "is_user": false, }
Duration: "instant"
Example
CODEcurl -i http://10.0.2.1/api/v2/map/token_reset -X POST -H "Content-Type: application/json" \ -d '{"reset":"default","which":"mapbox"}'
Network
/api/v2/net/online (GET) -- Check if the sensor is "online"
It pings some host and uses this info to determine if the sensor is online or not. Since this depends on the customer's network setup, it might not provide any meaningful information.
Response
CODE{ "_ok": true, "_message": "...", "online": true, }
Duration: Up to two seconds. Do not call this more often than every few seconds.
Example
CODEcurl -i http://10.0.2.1/api/v2/net/online
/api/v2/net/status (GET) -- Get network devices (interfaces) connection status
Response
CODE{ "_ok": true, "_message": "...", // For each (relevant) device: state = unknown|connected|connecting|disconnected|unavailable|disabled "eth0": { "state": "connected", "connection": "fp-navvr2-eth0-dhcp-client", "ip4addr": "172.22.1.44/20" }, "wlan0": { "state": "connected", "connection": "fp-navvr2-wlan0-fixposition", "ip4addr": "192.168.43.221/24" }, "wlan1": { "state": "disabled", "connection": "", "ip4addr": "" }, // Access point disabled "usb0": { "state": "unavailable", "connection": "", "ip4addr": "" }, }
Duration: "instant"
Example
CODEcurl -i http://10.0.2.1/api/v2/net/status
/api/v2/net/conn_get (GET) -- Get network connections config
Response
CODE{ "_ok": true, "_message": "...", // All available connections, including those from disabled interfaces (e.g. wlan0, wlan1) "connections": [ "fp-navvr2-eth0-dhcp-client", "fp-navvr2-eth0-dhcp-server", "fp-navvr2-eth0-static-ip", "fp-navvr2-wlan0-blabla", "fp-navvr2-wlan0-fixposition", "fp-navvr2-wlan1-access-point" ], "fp-navvr2-eth0-dhcp-client": { "auto": true, "ifname": "eth0", "connection": "fp-navvr2-eth0-dhcp-client", "ip4addr": "", "ip4gw": "", "ip4dns": "", "ip4method": "auto" }, "fp-navvr2-eth0-dhcp-server": { "auto": false, "ifname": "eth0", "connection": "fp-navvr2-eth0-dhcp-server", "ip4addr": "10.0.2.1/24", "ip4gw": "", "ip4dns": "", "ip4method": "auto" }, "fp-navvr2-eth0-static-ip": { "auto": false, "ifname": "eth0", "connection": "fp-navvr2-eth0-static-ip", "ip4addr": "10.0.2.10/24", "ip4dns": "1.1.1.1,8.8.8.8,8.8.4.4", "ip4gw": "10.0.2.1", "ip4method": "manual" }, "fp-navvr2-wlan0-blabla": { "auto": false, "ifname": "wlan0", "connection": "fp-navvr2-wlan0-blabla", "ip4addr": "", "ip4gw": "", "ip4dns": "", "ip4method": "auto", "ssid": "blabla", "keymgmt": "wpa-psk" }, "fp-navvr2-wlan0-fixposition": { "auto": true, "ifname": "wlan0", "connection": "fp-navvr2-wlan0-fixposition", "ip4addr": "", "ip4gw": "", "ip4dns": "", "ip4method": "auto", "ssid": "fixposition", "keymgmt": "wpa-psk" }, "fp-navvr2-wlan1-access-point": { "auto": true, "ifname": "wlan1", "connection": "fp-navvr2-wlan1-access-point", "ip4addr": "10.0.1.1/24", "ip4gw": "", "ip4dns": "", "ip4method": "shared", "ssid": "fp-abcdef", "keymgmt": "wpa-psk" }, }
Duration: "instant"
Example
CODEcurl -i http://10.0.2.1/api/v2/net/conn_get
/api/v2/net/conn_set (POST) -- Set network connection config
Request
CODE{ "connection": "fp-navvr2-wlan0-blabla", // Connection name // Only provide those fields that should be changed. At least one field must be provided. Not all combinations // make sense for all connections! E.g. do not remove the ip4addr from the access point! "auto": true, // true, false "ip4addr": "10.1.2.3/22", // IPv4 address and netmask, '' to remove "ip4gw": "10.1.2.1", // IPv4 gateway address, '' to remove "ip4dns": "10.99.99.99", // IPv4 DNS server addresse (comma-separated list), '' to remove "ip4method": "manual", // IPv4 method: "manual", "auto", "shared" "psk": "verysecret", // Wi-Fi password, only for Wi-Fi connections, cannot be removed "keymgmt": "wpa-psk", // Wi-Fi security, see /net/wifi_add API description below "ssid": "something" // Wi-Fi SSID, only for Wi-Fi connections, 2-32 printable chars, cannot be removed }
Response
CODE{ "_ok": true, "_message": "...", "fp-navvr2-wlan0-blabla": { "connection": "fp-navvr2-wlan0-blabla", "auto": false, "ifname": "wlan0", "ip4addr": "10.1.2.3/22", "ip4gw": "10.1.2.1", "ip4dns": "10.99.99.99" } }
It is very easy to mess up a connection by providing a bad combination of parameters!
Duration: "instant"
Example
CODEcurl -i http://10.0.2.1/api/v2/net/conn_set -X POST -H "Content-Type: application/json" \ -d '{"connection":"fp-navvr2-eth0-static", "auto": true, "ip4addr":"10.10.10.10/24","ip4gw":"10.10.10.1","ip4dns":"10.10.10.1","psk":"verysecret"}'
/api/v2/net/conn_up (POST) -- Connect network connection
Request
CODE{ "connection" : "fp-navvr2-wlan0-fixposition" }
Response
CODE{ "_ok": true, "_message": "..." }
Duration: This operation can take up to 60 seconds.
Example
CODEcurl -i http://10.0.2.1/api/v2/net/conn_up -X POST -H "Content-Type: application/json" \ -d '{"connection":"fp-navvr2-wlan0-fixposition"}'
/api/v2/net/conn_down (POST) -- Disconnect network connection
Request
CODE{ "connection" : "fp-navvr2-wlan0-fixposition" }
Response
CODE{ "_ok": true, "_message": "..." { "ssid": "fp-5cba80", "bssid": "c2:ee:40:3b:b1:b4", "mode": "infra", "chan": 11, "rate": 65, "signal": 57, "security": "WPA2" }, { "bssid": "c4:ad:34:f3:a8:a0", "ssid": "fixposition-guest", "mode": "infra", "chan": 8, "rate": 270, "signal": 59, "security": "WPA2" }, { "bssid": "c4:ad:34:85:fc:64", "ssid": "fixposition-guest", "mode": "infra", "chan": 112, "rate": 270, "signal": 57, "security": "WPA2" }, // ... }
Duration: This operation can take up to 60 seconds.
Example
CODEcurl -i http://10.0.2.1/api/v2/net/conn_down -X POST -H "Content-Type: application/json" \ -d '{"connection":"fp-navvr2-wlan0-fixposition"}'
/api/v2/net/conn_reset (POST) -- Reset all connections to default
Request
CODE{ "reset": "default" }
Response
CODE{ "_ok": true, "_message": "..." }
Duration: "instant"
The connections are not reset to default immediately. Instead, all connections are removed and replaced with the default connections on the next boot. Use with care!
Example
CODEcurl -i http://10.0.2.1/api/v2/net/conn_reset -X POST -H "Content-Type: application/json" \ -d '{"reset":"default"}'
/api/v2/net/wifi_list (GET) -- List available Wi-Fi networks
Response
CODE{ "_ok": true, "_message": "...", "networks": [ { "bssid": "01:02:03:04:05:06", "ssid": "fixposition", "mode": "infra", "chan": 11, "rate": 195, "signal": 42, "security": "WPA2" }, { "bssid": "02:03:04:05:06:07", "ssid": "fixposition-5", "mode": "infra", "chan": 128, "rate": 270, "signal": 59, "security": "WPA2" }, { "bssid": "03:04:05:06:07:08", "ssid": "fixposition-guest", "mode": "infra", "chan": 1, "rate": 270, "signal": 77, "security": "WPA2" }, { "bssid": "04:05:06:07:08:0a", "ssid": "fixposition-guest", "mode": "infra", "chan": 112, "rate": 270, "signal": 67, "security": "WPA2" } ] }
Duration: This operation can take up to 30 seconds.
Example
CODEcurl -i http://10.0.2.1/api/v2/net/wifi_list
/api/v2/net/wifi_add (POST) -- Add a Wi-Fi network connection
Request
CODE{ "ssid": "guguseli", "psk": "ahsosecret", "keymgmt": "wpa-psk" // "wpa-psk" for WPA-PSK (WPA2), (or, but currently not working: "sae" for SAE (WPA3)) // + optional other params, as for /net/conn_set }
Response
CODE{ "_ok": true, "_message": "...", "fp-navvr2-wlan0-guguseli": { "conn": "fp-navvr2-wlan0-guguseli", "auto": true, "ifname": "wlan0", "ip4addr": "", "ip4gw": "", "ip4dns": "", "ssid": "guguseli" } }
Duration: "instant"
Example
CODEcurl -i http://10.0.2.1/api/v2/net/wifi_add -X POST -H "Content-Type: application/json" \ -d '{"ssid":"guguseli", "auto": true, "psk":"ahsosecret", "keymgmt": "wpa-psk"}'
/api/v2/net/wifi_remove (POST) -- Remove a Wi-Fi network connection
Request
CODE{ "ssid": "guguseli" }
Response
CODE{ "_ok": true, "_message": "..." }
Duration: "instant"
Example
CODEcurl -i http://10.0.2.1/api/v2/net/wifi_remove -X POST -H "Content-Type: application/json" \ -d '{"ssid":"guguseli"}'
/api/v2/net/wifi_cfg (POST) -- Wi-Fi configuration
Request
CODE{ "action": "set", // "get", "set", "reset" // With action=set at least one parameter has to be given: "config_band": "a", // "a" (5 GHz), "bg" (2.4 GHz) or "off" (Wi-Fi disabled) "config_ap": false // true (enable access point) or false (disable access point) // For action=reset, the following must be given: // "reset": "default" // Reset to default config }
Response
CODE{ "_ok": true, "_message": "...", // Currently active (used) config "config_band": "a", "config_ap": false, // Saved config, becomes active on next boot "active_band": "bg", "active_ap": true }
Duration: "instant"
Example
CODEcurl -i http://10.0.2.1/api/v2/net/wifi_cfg -X POST -H "Content-Type: application/json" \ -d '{"action":"set","config_band":"a"}'
Camera
/api/v2/camera/calib_check (GET) -- Check if camera calibration is present
Response
CODE{ "_ok": true, "_message": "...", "calib_file_ok": true, // Calib file present (true) or missing (false) "calib_version": 0, // (only valid if calib_file_ok) Legacy file name (0) or new API file name (1) }
Duration: "instant"
Example
CODEcurl -i http://10.0.2.1/api/v2/camera/calib_check
/api/v2/camera/calib_upl (POST) -- Upload camera calibration file
Request
multipart/form-data
form upload with parametercalib_file
Response
CODE{ "_ok": true, "_message": "..." }
Duration: "instant"
Examples
CODEcurl -i http://10.0.2.1/api/v2/camera/calib_upl -X POST -H "Content-Type: multipart/form-data" \ -F "calib_file=@calib.yaml"
CODE<form action="/api/v2/cam/calib_upl" method="post" enctype="multipart/form-data"> <input type="file" name="calib_file" accept=".yaml" /> <input type="submit"/> </form>
Notes
To apply the uploaded calibration either reboot the sensor or restart the camera (see the /ctrl/action API)
/api/v2/camera/rec_ls (POST) -- List available recordings and disk info
Request
CODE{ // It takes no parameters, but still is a POST request for compatibility with /log/ls API }
Response
CODE{ "_ok": true, "_message": "...", "files": [ // Ordered by name { "name": "calib_2022-12-27-10-02-07.bag", "disk": "internal", "size": 252423809, "time": 1672956972 }, { "name": "calib_2022-12-26-18-20-45.bag", "disk": "internal", "size": 310921611, "time": 1672078866 } ], "disk": { "name": "internal", "avail": true, "total": 6173556736, "free": 5209104384, "used": 964452352 } }
Duration: "instant"
Example
CODEcurl -i http://10.0.2.1/api/v2/camera/rec_ls -X POST -H "Content-Type: application/json" \ -d '{}'
/api/v2/camera/rec_dl (GET) -- Download bag file
Request
Query parameter
name
with the bag file name
Response
Download file
Duration: download should start instantly
Example
CODEcurl -i http://10.0.2.1/api/v2/camera/rec_dl?file=calib_2022-12-26-18-20-45.bag
/api/v2/camera/rec_rm (POST) -- Remove (delete) recording(s)
Request
CODE{ "files" : [ "calib_2022-12-27-10-02-07.bag" ] // One or more files to delete }
Response
CODE{ "_ok": true, "_message": "...", "files": [ { "name": "calib_2022-12-26-18-20-45.bag", "disk": "internal", "size": 310921611, "time": 1672078866 } ], "disk": { "name": "internal", "avail": true, "total": 6173556736, "free": 5209104384, "used": 964452352 } }
Duration: "instant"
Example
CODEcurl http://10.0.2.1/api/v2/camera/rec_rm -X POST -H "Content-Type: application/json" \ -d '{"files":["calib_2022-12-27-10-02-07.bag"]}'
/api/v2/camera/record (POST) -- Record camera calibration sequence
Request
CODE{ "action" : "start" // "start", "stop", "status" }
Response
CODE{ "_ok": true, "_message": "...", "running": true, }
Duration: ~2 seconds ("status") up to many seconds ("start", "stop")
Example
CODEcurl -i http://10.0.2.1/api/v2/camera/record -X POST -H "Content-Type: application/json" \ -d '{"action":"start"}'
/api/v2/camera/stream (GET) -- Camera image stream (low rate, low resolution, distorted)
The camera stream should only be used for debugging and development (e.g., checking the camera alignment). Operational and continuous use is not supported.
Response
A multipart/x-mixed-replace stream of images (image/jpeg)
Duration: never-ending
Examples
CODEcurl -i http://10.0.2.1/api/v2/camera/stream
CODE<img src="http://10.0.2.1/api/v2/camera/stream"/>
Control
/api/v2/ctrl/status (GET) -- Get system and services status
Response
CODE{ "_ok": true, "_message": "...", // System state: "starting", "running", "stopping", "warning", "unknown" "system": "running", // Service state: "running", "stopped", "unknown" "core": "running", "rtk": "running", "camera": "running", "fusion": "running", // s.a. /fusion/ctrl "websocket": "running", "wheels": "running", "gnss": "running", "imu": "running", "io": "running", }
Duration: "instant"
Example
CODEcurl -i http://10.0.2.1/api/v2/ctrl/status
/api/v2/ctrl/action (POST) -- System control (reboot, shutdown) and services (start, stop, restart)
Request
CODE{ // Either control system: "reboot", "shutdown" "system": "reboot", // Or control one or more services: "rtk": "restart", // "restart" "camera": "restart", // "restart" "fusion": "stop", // "start", "stop", "restart" "websocket": "restart", // "restart" "wheels": "restart", // "restart" "io": "reload", // "reload" (and also "restart", but don't do that) // ...and some more, see config.php }
Response
CODE{ "_ok": true, "_message": "...", "system": "running", "core": "running", "rtk": "running", "camera": "running", "fusion": "stopped", "websocket": "running", "wheels": "running", "gnss": "running", "imu": "running", "io": "running", }
Duration: reboot and shutdown delayed by 2 seconds (the actions itself can take a long time), service control can take a while, too (more actions take longer!)
Examples
CODEcurl -i http://10.0.2.1/api/v2/ctrl/action -X POST -H "Content-Type: application/json" \ -d '{"system":"reboot"}' curl -i http://10.0.2.1/api/v2/ctrl/action -X POST -H "Content-Type: application/json" \ -d '{"rtk":"restart","camera":"restart","fusion":"stop"}'
Logging (recording)
/api/v2/log/disk (POST) -- Disk actions (mount, umount, info)
Request
CODE{ "action": "umount", // "status", "mount", "umount" "disk": "external" // only required for "mount" and "umount" }
Response
CODE{ "_ok": true, "_message": "...", "disks": [ // All disks are reported, independent from the "disk" request param { "name": "internal", "avail": true, "mount": true, "total": 6173556736, "free": 5479464960, "used": 694091776 }, { "name": "external", "avail": true, "mount": true, "total": 2952544256, "free": 1104420864, "used": 1848123392 } ] }
Duration: "instant"
Examples
CODEcurl -i http://10.0.2.1/api/v2/log/disk -X POST -H "Content-Type: application/json" \ -d '{"action":"status"}' curl -i http://10.0.2.1/api/v2/log/disk -X POST -H "Content-Type: application/json" \ -d '{"disk":"external","action":"umount"}'
/api/v2/log/ls (POST) -- Get list of available logs on all disks
Request
CODE{ "disk": "internal" }
Response
CODE{ "_ok": true, "_message": "...", "files": [ // Ordered by name { "name": "2022-11-24-23-09-09_minimal", "disk": "internal", "size": 1992258, "time": 1669331349 }, { "name": "2022-11-24-23-12-48_minimal", "disk": "internal", "size": 8201396, "time": 1669331568 }, { "name": "2022-11-24-23-15-54_minimal", "disk": "internal", "size": 8844289, "time": 1669331754 } ], "disk": { "name": "internal", "avail": true, "mount": true, "total": 6173556736, "free": 5479464960, "used": 694091776 } }
Duration: "instant"
Example
CODEcurl -i http://10.0.2.1/api/v2/log/ls -X POST -H "Content-Type: application/json" \ -d '{"disk":"internal"}'
/api/v2/log/dl (GET) -- Download a log
Request
Query parameter
disk
with the disk nameQuery parameter
name
with the log name
Response
Download file
Duration: download should start instantly
Example
CODEcurl -OJ "http://10.0.2.1/api/v2/log/dl?disk=internal&name=2022-11-24-23-09-26_minimal"
/api/v2/log/rm (POST) -- Delete log(s)
Request
CODE{ "disk": "internal", // "internal", "external" "files": [ "2022-11-24-23-09-26_minimal" ] // List of files to delete }
Response
CODE{ "_ok": true, "_message": "", "files": [ { "name": "2022-11-24-23-09-09_minimal", "disk": "internal", "size": 1992258 }, { "name": "2022-11-24-23-12-48_minimal", "disk": "internal", "size": 8201396 }, { "name": "2022-11-24-23-15-54_minimal", "disk": "internal", "size": 8844289 }, ], "disk": { "name": "internal", "avail": true, "mount": true, "total": 6173556736, "free": 5479464960, "used": 694091776 } }
Duration: "instant"
Example
CODEcurl -i http://10.0.2.1/api/v2/log/rm -X POST -H "Content-Type: application/json" \ -d '{"disk":"internal","files":["2022-11-24-23-12-48_minimal"]}'
/api/v2/record/info (GET) -- Logging information, such as available logging profiles (levels)
Request
This request takes no parameters
Response
CODE{ "_ok": true," _message": "...", "profiles": [ { "name": "maximal", "label": "Maximal recording", "descr": "Largest files, ...", "net_allowed_ifs": [ "eth", "usb" ] }, { "name": "medium", "label": "Medium recording", "descr": "Larger files, ...", "net_allowed_ifs": [ "eth", "usb", "wlan" ] }, { "name": "minimal", "label": "Minimal recording", "descr": "Smallest files, ...", "net_allowed_ifs": [ "eth", "usb", "wlan" ]}, // ... ] }
Duration: "instant"
Examples
CODEcurl -i http://10.0.2.1/api/v2/record/info
/api/v2/record/status (GET) -- Logging status
Request
This request takes no parameters
Response
CODE{ "_ok": true," _message": "...", "state": "logging", // Logging state: "stopped", "logging", "stopping" "profile": "medium", // Configuration profile name "target": "internal", // Logging target: "download", "internal", "external" "filename": "vrtk2_5d6f64_2024-02-03-13-24-53_medium.fpl", // Logfile name "queue_size": 0, // Queue size "queue_peak": 59, // Queue peak size "queue_skip": 0, // Number of skipped messages "log_count": 21440, // Number of logged messages "log_errors": 0, // Number of messages failed to log (failed to write/send) "log_size": 31926940, // Total size of logged messages [bytes] "log_duration": 43, // Duration of logging [s] "log_remaining": 7326, // Estimated remaining logging duration [s], 0 = none/unknown "int_size": 6028864, // Internal disk size [KiB] "int_avail": 5517216, // Internal disk available [KiB] "int_ok": true, // Internal disk ok (available and enough remaining space) "ext_size": 976759936, // External disk size [KiB] (0 = disk not available) "ext_avail": 625565696, // External disk available [KiB] (0 = disk not available) "ext_ok": true // Internal disk ok (available and enough remaining space) }
Duration: "instant"
Examples
CODEcurl -i http://10.0.2.1/api/v2/record/status
/api/v2/record/start (POST) -- Start logging
Request
CODE{ "target": "internal", // "internal", "external", "download", "debuglog" "profile": "medium" // profile name from /record/info }
Response
Request
target
=internal
orexternal
:CODE{ "_ok": true, // True if logging started successfully, false otherwise "_message": "...", // Message indicating the problem in case of _ok == false, e.g. "logging is already started" "state": "logging", // On success (_ok == true) state should be 'logging' // ...and all other fields documented in the response to the /record/status request above }
Request
target
=download
On success a file download is started
On failure the above JSON response (with _ok = false) is returned
Duration: ~1-3 seconds
Examples
CODEcurl -i http://10.0.2.1/api/v2/record/start -X POST -H "Content-Type: application/json" \ -d '{"target":"internal","profile":"medium"}' curl -OJ http://10.0.2.1:21100/start -X POST -H "Content-Type: application/json" \ -d '{"target":"download","profile":"medium"}' # Note the different port number and URL path for log download!
Notes
In case of target
download
, the request must be made to port 21100. It is not possible to start network logging via the API on port 80.Interrupting the download, such as terminating the curl command, yields a unclean terminated and incomplete logfile. Always use the /record/stop API to initiate stopping the logging and wait for the download to complete.
See https://github.com/fixposition/fixposition_utility/tree/main/record for example scripts using this API.
/api/v2/record/stop (POST) -- Stop logging
Request
This request takes no parameters
Response
CODE{ "_ok": true, // True if stopping successfully, false otherwise "_message": "...", // Message indicating the problem in case of _ok == false, e.g. "logging is already started" "state": "stopping", // On success (_ok == true) state should be 'stopping' // ...and all other fields documented in the response to the /record/status request above }
Duration: ~1-3 seconds
Examples
CODEcurl -i http://10.0.2.1/api/v2/record/stop -X POST -d ''
Note
This initiates the stopping logging. It takes a up to 60 seconds for the logging to terminate and close the logfile or stop the download. Observe the
state
field in the /record/status response, which should go fromstopping
tostopped
once the logging has finished.
Fusion
/api/v2/fusion/ctrl (POST) -- Control Fusion service
Request
CODE{ "action": "status" // "status", "enable", "disable", "reset" (only when running) }
Use /ctrl/action
to start/stop/restart fusion
Response
CODE{ "_ok": true, "_message": "...", "state": "stopped", // "stopped", "running" (s.a. /ctrl/status) "autostart": true, }
Duration: "instant"
Example
CODEcurl -i http://10.0.2.1/api/v2/fusion/ctrl -X POST -H "Content-Type: application/json" \ -d '{"action":"status"}'
/api/v2/fusion/data (POST) -- Fusion persistent data
Request
CODE{ "stationary": "remove", // "" (or param missing), "remove" "warmstart": "" }
Response
CODE{ "_ok": true, "_message": "...", "stationary": "missing", // "present", "missing" "warmstart": "present", }
Duration: "instant"
Before configuring or resetting any data, make sure to stop fusion first! Otherwise, the changes will only take place after the next fusion restart.
curl -i http://10.0.2.1/api/v2/ctrl/action -X POST -H "Content-Type: application/json" \
-d '{"fusion":"stop"}'
Example:
Get current status
CODEcurl -i http://10.0.2.1/api/v2/fusion/data -X POST -H "Content-Type: application/json" \ -d '{"warmstart":""}'
Remove data for fusion data reset
CODEcurl -i http://10.0.2.1/api/v2/fusion/data -X POST -H "Content-Type: application/json" \ -d '{"warmstart":"remove"}'
/api/v2/fusion/initialpose (POST) -- Fusion saved poses management
Request
CODE- Save: ```jsonc { "action": "save", "slot": 0, // slot number to perform the saving "label": "label" // label of the slot } ``` - Load: ```jsonc { "action": "load", "slot": 0 // slot number to perform the loading } ``` - Delete: ```jsonc { "action": "delete", "slot": 0 // slot number to perform the deletion ("*" for a complete deletion) } ``` - Get: ```jsonc { "action": "get" } ``` - Set: ```jsonc { "action": "set", "states": [ { ... }, { ... }, { ... }, { ... }, { ... } ] // states to be set (only needed in set) } ``` - Note that all states have to be provided. The suggested use is to "get" the states, modify the state in question, then "set" all states
Response
CODE{ "_ok": true, "_message": "...", "states": [ // saved states { // State 0 is valid, data is a saved initial pose "valid": true, // - State is valid "label": "something", // - Label ... // - Data (various, unspecified fields and values) }, { // State 1: invalid, i.e. no data saved "valid": false, // - State is invalid "label": "", // - Label empty ... // - Data (various, unspecified fields and values) }, { ... }, { ... }, { ... } ] // States 2-4 }
Duration: "instant"
Examples
Save pose
CODEcurl -i http://10.0.2.1/api/v2/fusion/initialpose -X POST -H "Content-Type: application/json" \ -d '{"action":"save", "slot":1, "label":"label_1"}'
Load pose
CODEcurl -i http://10.0.2.1/api/v2/fusion/initialpose -X POST -H "Content-Type: application/json" \ -d '{"action":"load", "slot":1}'
Delete pose
CODEcurl -i http://10.0.2.1/api/v2/fusion/initialpose -X POST -H "Content-Type: application/json" \ -d '{"action":"delete", "slot":1}'
Delete all
CODEcurl -i http://10.0.2.1/api/v2/fusion/initialpose -X POST -H "Content-Type: application/json" \ -d '{"action":"delete", "slot":"*"}'
Get poses
CODEcurl -i http://10.0.2.1/api/v2/fusion/initialpose -X POST -H "Content-Type: application/json" \ -d '{"action":"get"}'
Set poses
CODEcurl -i http://10.0.2.1/api/v2/fusion/initialpose -X POST -H "Content-Type: application/json" \ -d '{"action":"set", "states":[ { ... }, { ... }, { ... }, { ... }, { ... } ]}'
Webinterface
/api/v2/web/pw_get (GET) -- Get password protection state
Response
CODE{ "_ok": true, "_message": "...", "enabled": false, // true = user/pass is set "active": false, // true = user/pass is required by lighttpd (once enabled it becomes active on restart) "changed": false // true = config has changed (clears on restart) }
Duration: "instant"
Example
CODEcurl -i http://10.0.2.1/api/v2/web/pw_get
/api/v2/web/pw_set (POST) -- Enable password protection
Request
CODE{ "user": "test", // username (4-100 chars) "pass": "test" // password (4-100 chars) }
Response
CODE{ "_ok": true, "_message": "...", "enabled": true // Password protection now enabled, becomes active on reboot }
Duration: "instant"
Example
CODEcurl -i http://10.0.2.1/api/v2/web/pw_set -X POST -H "Content-Type: application/json" \ -d '{"user":"test","pass":"test"}'
/api/v2/web/pw_reset (POST) -- Reset password protection to default (i.e., remove it)
Request
CODE{ "reset": "default" // Password protection now disabled, becomes inactive on reboot }
Response
CODE{ "_ok": true, "_message": "...", "enabled": false }
Duration: "instant"
Example
CODEcurl -i http://10.0.2.1/api/v2/web/pw_reset -X POST -H "Content-Type: application/json" \ -d '{"reset":"default"}'
I/O (user_io)
/api/v2/io/info (GET) -- Get I/O ports and messages info
Response
CODE{ "_ok": true, "_message": "...", "ports": { ... }, // see user_io docu "messages": { ... } // see user_io docu }
Duration: "instant"
Example
CODEcurl -i http://10.0.2.1/api/v2/io/info
Params
/api/v2/params/config/get (GET) -- Get current configuration parameters
Response
CODE{ "_ok": true, "_message": "...", "params": { ... } // All parameters, see default_customer_config.yaml for docu }
Duration: "instant"
Example
CODEcurl -i http://10.0.2.1/api/v2/params/config/get
/api/v2/params/config/def (GET) -- Get default configuration (a.k.a. customer config) parameters
Response
CODE{ "_ok": true, "_message": "...", "params": { ... } // All parameters }
Duration: "instant"
Example
CODEcurl -i http://10.0.2.1/api/v2/params/config/def
/api/v2/params/config/set (POST) -- Set current configuration (a.k.a. customer config) parameters
Request
CODE{ "params": { // Some or all parameters to change ... } }
Response
CODE{ "_ok": true, "_message": "...", "params": { // All parameters ... } }
Duration: "instant"
Example
Set housing name
CODEcurl -i http://10.0.2.1/api/v2/params/config/set -X POST -H "Content-Type: application/json" \ -d '{"params":{"housing":"blabla"}}'
Set ENU Output mode
CODEcurl -i http://10.0.2.1/api/v2/params/config/set -X POST -H "Content-Type: application/json" \ -d '{"params":{"io":{"tf":{"enu0_mode":"manual"}}}}'
Set a position for ENU Output manually
CODEcurl -i http://10.0.2.1/api/v2/params/config/set -X POST -H "Content-Type: application/json" \ -d '{"params":{"io":{"tf":{"t_ecef_enu0":[4278387.00, 635620.00, 4672340.00]}}}}'
Enable for messages to be output on respective ports
CODEcurl -i http://172.22.1.29/api/v2/params/config/set -X POST -H "Content-Type: application/json" \ -d '{"params":{"io":{"ports":{"TCP1":{"rates_out":{"FP_A-ODOMETRY":1, "FP_A-LLH":1}},"TCP2":{"rates_out":{"FP_A-ODOMETRY":1}}}}}}'
/api/v2/params/config/reset (POST) -- Reset current configuration (a.k.a. customer config) parameters to default
Request
CODE{ "reset": "default" }
Response
CODE{ "_ok": true, "_message": "...", "params": { // All parameters ... } }
Duration: "instant"
Before configuring or resetting any data, make sure to stop fusion first! Otherwise, the changes will only take place after the next fusion restart.
curl -i http://10.0.2.1/api/v2/ctrl/action -X POST -H "Content-Type: application/json" \
-d '{"fusion":"stop"}'
Example
CODEcurl -i http://10.0.2.1/api/v2/params/config/reset -X POST -H "Content-Type: application/json" \ -d '{"reset":"default"}'
/api/v2/params/camera/get (GET) -- Get camera information
Response
CODE{ "_ok": true, "_message": "...", "params": { // All parameters ... } }
Duration: "instant"
Example
CODEcurl -i http://10.0.2.1/api/v2/params/camera/get
/api/v2/params/hw/get (GET) -- Get hardware information
Response
CODE{ "_ok": true, "_message": "...", "params": { // All parameters "MAC": "6d9d18", "NAME": "nav-vr2", "REVISION": "1.2a" "housings": { "ip67": { "t_body_sensor": [ -0.034, 0.002, 0.016 ], "q_body_sensor": [ 0, 0, 0, 1 ], "t_sensor_antenna1": [ 0.02, -0.175, -0.02 ], "t_sensor_antenna2": [ 0.02, 0.175, -0.02 ], "dual_antenna": true }, "3d_print": { ... }, "custom": { ... }, }, ... } }
Duration: "instant"
Example
CODEcurl -i http://10.0.2.1/api/v2/params/hw/get
User data
Available since 2.85.3
Users can use this data to store a string and a JSON object on the sensor. Possible use-cases include inventory, fleet and configuration management.
/api/v2/misc/data_get (GET) -- Get user data
Request
This request takes no parameters
Response
CODE{ "_ok": true, "_message": "...", "user_string": "something", // Any string (of printable characters), up to 500 bytes "user_json": { "some": "thing" } // {} or [], up to 10'000 bytes (serialised) }
Duration: "instant"
Example
CODEcurl -i http://10.0.2.1/api/v2/misc/data_get
/api/v2/misc/data_set (POST) -- Set user data
Request
CODE{ "user_string": "something", "user_json": { "some": "thing" } }
Response
CODE{ "_ok": true, "_message": "...", "user_string": "something", // Any string (of printable characters), up to 500 bytes "user_json": { "some": "thing" } // {} or [], up to 10'000 bytes (serialised) }
Duration: “instant”
Example
CODEcurl -i http://10.0.2.1/api/v2/misc/data_set -X POST -H "Content-Type: application/json" \ -d '{"user_string":"something","user_json":{"some":"thing"}}'
/api/v2/misc/data_reset (POST) -- Reset user data
Request
CODE{ "reset": "default" }
Response
CODE{ "_ok": true, "_message": "...", "user_string": "", "user_json": { } }
Duration: “instant”
Example
CODEcurl -i http://10.0.2.1/api/v2/misc/data_reset -X POST -H "Content-Type: application/json" \ -d '{"reset":"default"}'
Configuration backup and restore
Available since 2.85.3
This API can be used to backup and restore a sensor's configuration and replicate it to one or more other sensors. However, it is not intended to replace the existing configuration API in any other case.
Notes:
Credentials, such as web interface protection or Wi-Fi keys, cannot be retrieved from the sensor. The '/backup/get' API always returns such fields as the empty string. When restoring a configuration backup to a sensor via the '/backup/set' API, the behavior of the empty fields varies. Specifically:
The "user" and "pass" fields are in the "web" configuration section. Empty fields mean no password protection.
The "psk" fields for Wi-Fi connections are in the "net" section. Such connections are ignored, and their configuration is not restored; it is left in the current state.
If setting the configuration fails, no detailed information on what exactly has failed is provided. Use the individual API methods to get more information. For example, a too-short web password is reported as such in '/web/pw_set', but in '/backup/set', it just says that the "web" section has failed.
For '/backup/set', sections can be omitted, and the respective configuration is untouched. However, all sections that are given must be complete.
On restore Wi-Fi client connections are only added or modified. Existing Wi-Fi client connections not present in the restore data are left untouched.
The format of the configuration data is very delicate and there are not many checks. It's VERY easy to mess things up by loading bad configuration. For example, by providing the same Wi-Fi connection or same SSID multiple times, illegal field names, contradicting data, etc. In case of weird behaviour, factory reset the sensor and try again.
/api/v2/backup/get (GET) -- Get a configuration backup
Request
This request takes no parameters
Response
CODE"_ok": true, "_message": "...", // Meta data to identify the sensor and the software version from which the configuration is. // See also the /sys/info API "meta": { "uid": "fp-123abc", // Sensor UID "sw_ver": "fp_release_1.2.3_123" // Software version string }, // Configuration, organised into different sections, named according to the respective API "config": { // CAN interface configuration, see the /can/if_... API "can": { "config_enabled": true, "config_bitrate": 250000, "config_dbitrate": 250000 }, // GNSS configuration "gnss": { // Correction data configuration, see the /gnss/rtk_... API "rtk": { "source": "ntripcli", "ntrip_user": "lukas", "ntrip_pass": "meier", "ntrip_host": "ntrip.fixposition.com", "ntrip_port": 1234, "ntrip_mount": "FOO", "gga_mode": "manual", "gga_lat": 47.5, "gga_lon": 8.3, "gga_height": 400 } }, // Map configuration "map": { // Mapbox token, see the /map/token_... API "mapbox": "" // "" = built-in default token, otherwise a user-supplied token }, // Fusion configuration (see also the "params" section below) "fusion": { "autostart": "enabled" // Fusion autostart: "enabled" or "disabled" }, // Webinterface configuration "web": { // Password protection, see /web/pw_... API. See notes below! "user": "", "pass": "" }, // Misc configuration "misc": { // Advanced options, see /misc/opt_... API "options": "", // User data, see /misc/data_... API "user_string": "something", "user_json": { "some": "thing" } }, // Time configuration "time": { // PTP configuration, see /time/ptp_... API "ptp": { "autostart": "disabled", "profile": "ptpv2" } }, "net": { // Wi-Fi configuration, see /net/wifi_cfg API "wifi": { "config_band": "bg", "config_ap": true }, // Network connection config, see /net/conn_... API "conn": [ { "connection": "fp-navvr2-eth0-static-ip", "auto": false, "ifname": "eth0", "ip4addr": "10.0.2.10/24", "ip4gw": "10.0.2.1", "ip4dns": "1.1.1.1,8.8.8.8,8.8.4.4", "ip4method": "manual" }, // ... ] }, // Parameters, see /params/config/... APIO "params": { //... } } }
Duration: ~2 seconds
Example
CODEcurl http://10.0.2.1/api/v2/backup/get > backup.json
/api/v2/backup/set (POST) -- Restore a configuration backup
Request
CODE{ // The configuration data to restore "config": { // Sections and contents like in /backup/get. Sections can be omitted in restore. // However, each section that is provided must be complete. "can": { ... }, "gnss": { ... }, "map": { ... }, "fusion": { ... }, "web": { ... }, "misc": { ... }, "time": { ... }, "net": { ... }, "params": { ... } } }
Response
CODE{ "_ok": true, "_message": "...", // On success (_ok = true) also the same data as in /backup/get is returned "meta": { ... }, "config": { ... } }
Duration: up to 30 seconds
Example
CODEcurl -i http://10.0.2.1/api/v2/backup/set -X POST -H "Content-Type: application/json" \ -d @backup.json