API Documentation

General
API Responsiveness Monitoring
System info
CAN
GNSS
Map
Network
Camera
Control
Logging (recording)
Fusion
Webinterface
I/O (user_io)
Params
User data
Configuration backup and restore

General

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:

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

Response

{
"_ok": true, "_message": "..." // always true, unless server is broken
}

Duration: "instant"
Example

curl -i http://10.0.2.1/api/v2/api_up

System info

/api/v2/sys/load (GET) -- System load

Response

{
"_ok": true, "_message": "...",
"system_load": 1.81 // System load [-]
}

Duration: "instant"
Example

curl -i http://10.0.2.1/api/v2/sys/load

/api/v2/sys/cpu (GET) -- CPU load and temperature

Response

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

curl -i http://10.0.2.1/api/v2/sys/load

/api/v2/sys/uptime (GET) -- System uptime

Response

{
"_ok": true, "_message": "...",
"uptime": 82306 // [s]
}

Duration: "instant"
Example

curl -i http://10.0.2.1/api/v2/sys/uptime

/api/v2/sys/load_cpu_uptime (GET) -- All of the above

Response

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

curl -i http://10.0.2.1/api/v2/sys/load_cpu_uptime

/api/v2/sys/info (GET) -- System information (versions, etc.) [strings]

Response

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

curl -i http://10.0.2.1/api/v2/sys/info

/api/v2/sys/timesync (GET) -- Get system time sync status [strings]

Response

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

curl -i http://10.0.2.1/api/v2/sys/timesync

CAN

/api/v2/can/if_get (GET) -- Get CAN interface saved and active config

Response

{

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

curl -i http://10.0.2.1/api/v2/can/if_get

/api/v2/can/if_set (POST) -- Set CAN interface saved config

Request

{

    "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

{

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

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

{
"reset": "default"
}

Duration: "instant"
Response

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

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

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

curl -i http://10.0.2.1/api/v2/gnss/rtk_status

/api/v2/gnss/rtk_get (GET) -- Get RTK correction stream parameters

Response

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

curl -i http://10.0.2.1/api/v2/gnss/rtk_get

/api/v2/gnss/rtk_set (POST) -- Set RTK correction stream parameters

Request

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

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

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

{
"reset": "default"
}

Duration: "instant"
Response

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

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

{
"gnss": 1, // 1 or 2
"type": "hot" // "hot", "warm" or "cold"
}

Response

{
"_ok": true, "_message": "...",
}

Duration: "instant" (the actual receiver reset can take a second or so)
Example

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

{
"which": "mapbox"
}

Response

{
"_ok": true, "_message": "...",
"token": "builtinnotsecrettoken",
"is_user": false,
}

Duration: "instant"
Example

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

{
"which": "mapbox",
"token": "verysecretnot"
}

Response

{
"_ok": true, "_message": "...",
"token": "verysecretnot",
"is_user": true,
}

Duration: "instant"
Example

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

{
"reset": "default",
"which": "mapbox"
}

Response

{
"_ok": true, "_message": "...",
"token": "builtinnotsecrettoken",
"is_user": false,
}

Duration: "instant"
Example

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

{
"_ok": true, "_message": "...",
"online": true,
}

Duration: Up to two seconds. Do not call this more often than every few seconds.
Example

curl -i http://10.0.2.1/api/v2/net/online

/api/v2/net/status (GET) -- Get network devices (interfaces) connection status

Response

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

curl -i http://10.0.2.1/api/v2/net/status

/api/v2/net/conn_get (GET) -- Get network connections config

Response

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

curl -i http://10.0.2.1/api/v2/net/conn_get

/api/v2/net/conn_set (POST) -- Set network connection config

Request

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

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

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

{
"connection" : "fp-navvr2-wlan0-fixposition"
}

Response

{
"_ok": true, "_message": "..."
}

Duration: This operation can take up to 60 seconds.
Example

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

{
"connection" : "fp-navvr2-wlan0-fixposition"
}

Response

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

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

{
"reset": "default"
}

Response

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

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

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

curl -i http://10.0.2.1/api/v2/net/wifi_list

/api/v2/net/wifi_add (POST) -- Add a Wi-Fi network connection

Request

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

Duration: "instant"
Example

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

{
"ssid": "guguseli"
}

Response

{
"_ok": true, "_message": "..."
}

Duration: "instant"
Example

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

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

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

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

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

curl -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 parameter calib_file
Response

{
"_ok": true, "_message": "..."
}

Duration: "instant"
Examples

curl -i http://10.0.2.1/api/v2/camera/calib_upl -X POST -H "Content-Type: multipart/form-data"
-F "[email protected]"

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

{ // It takes no parameters, but still is a POST request for compatibility with /log/ls API
}

Response

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

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

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

{
"files" : [ "calib_2022-12-27-10-02-07.bag" ] // One or more files to delete
}

Response

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

curl 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

{
"action" : "start" // "start", "stop", "status"
}

Response

{
"_ok": true, "_message": "...",
"running": true,
}

Duration: ~2 seconds ("status") up to many seconds ("start", "stop")
Example

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

curl -i http://10.0.2.1/api/v2/camera/stream

Control

/api/v2/ctrl/status (GET) -- Get system and services status

Response

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

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

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

{
"_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, as well (more actions take longer!)
Examples

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

{
"action": "umount", // "status", "mount", "umount"
"disk": "external" // only required for "mount" and "umount"
}

Response

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

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

{
"disk": "internal"
}

Response

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

curl -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 name
- Query parameter name with the log name
Response
- Download file
Duration: download should start instantly
Example

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

{
"disk": "internal", // "internal", "external"
"files": [ "2022-11-24-23-09-26_minimal" ] // List of files to delete
}

Response

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

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

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

curl -i http://10.0.2.1/api/v2/record/info

/api/v2/record/status (GET) -- Logging status

Request
- This request takes no parameters
Response

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

curl -i http://10.0.2.1/api/v2/record/status

/api/v2/record/start (POST) -- Start logging

Request

{
"target": "internal", // "internal", "external", "download", "debuglog"
"profile": "medium" // profile name from /record/info
}

Response, request target = internal or external:

{

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

}

Response, 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

curl -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!

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 this GitHub page for example scripts using this API.

/api/v2/record/stop (POST) -- Stop logging

Request
- This request takes no parameters
Response

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

curl -i http://10.0.2.1/api/v2/record/stop -X POST -d ''

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 from stopping to stopped once the logging has finished.

Fusion

/api/v2/fusion/ctrl (POST) -- Control Fusion service

Request

{
"action": "status" // "status", "enable", "disable", "reset" (only when running)
}

Use /ctrl/action to start/stop/restart fusion

Response

{
"_ok": true, "_message": "...",
"state": "stopped", // "stopped", "running" (s.a. /ctrl/status)
"autostart": true,
}

Duration: "instant"
Example

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

{
"stationary": "remove", // "" (or param missing), "remove"
"warmstart": ""
}

Response

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

Examples:

Get current status

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

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

- 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

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

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

curl -i http://10.0.2.1/api/v2/fusion/initialpose -X POST -H "Content-Type: application/json"
-d '{"action":"load", "slot":1}'

Delete pose

curl -i http://10.0.2.1/api/v2/fusion/initialpose -X POST -H "Content-Type: application/json"
-d '{"action":"delete", "slot":1}'

Delete all

curl -i http://10.0.2.1/api/v2/fusion/initialpose -X POST -H "Content-Type: application/json"
-d '{"action":"delete", "slot":"*"}'

Get poses

curl -i http://10.0.2.1/api/v2/fusion/initialpose -X POST -H "Content-Type: application/json"
-d '{"action":"get"}'

Set poses

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

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

curl -i http://10.0.2.1/api/v2/web/pw_get

/api/v2/web/pw_set (POST) -- Enable password protection

Request

{
"user": "test", // username (4-100 chars)
"pass": "test" // password (4-100 chars)
}

Response

{
"_ok": true, "_message": "...",
"enabled": true // Password protection now enabled, becomes active on reboot
}

Duration: "instant"
Example

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

{
"reset": "default" // Password protection now disabled, becomes inactive on reboot
}

Response

{
"_ok": true, "_message": "...",
"enabled": false
}

Duration: "instant"
Example

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

{
"_ok": true, "_message": "...",
"ports": { ... }, // see user_io docu
"messages": { ... } // see user_io docu
}

Duration: "instant"
Example

curl -i http://10.0.2.1/api/v2/io/info

Params

/api/v2/params/config/get (GET) -- Get current configuration parameters

Response

{
"_ok": true, "_message": "...",
"params": { ... } // All parameters, see default_customer_config.yaml for docu
}

Duration: "instant"
Example

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

{
"_ok": true, "_message": "...",
"params": { ... } // All parameters
}

Duration: "instant"
Example

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

{
"params": { // Some or all parameters to change
...
}
}

Response

{
"_ok": true, "_message": "...",
"params": { // All parameters
...
}
}

Duration: "instant"
Example

curl -i http://10.0.2.1/api/v2/params/config/set -X POST -H "Content-Type: application/json"
-d '{"params":{"housing":"blabla"}}'

/api/v2/params/config/reset (POST) -- Reset current configuration (a.k.a. customer config) parameters to default

Request

{
"reset": "default"
}

Response

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

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

{
"_ok": true, "_message": "...",
"params": { // All parameters
...
}
}

Duration: "instant"
Example

curl -i http://10.0.2.1/api/v2/params/camera/get

/api/v2/params/hw/get (GET) -- Get hardware information

Response

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

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

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

curl -i http://10.0.2.1/api/v2/misc/data_get

/api/v2/misc/data_set (POST) -- Set user data

Request

{
"user_string": "something",
"user_json": { "some": "thing" }
}

Response

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

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

{
"reset": "default"
}

Response

{
"_ok": true, "_message": "...",
"user_string": "",
"user_json": { }
}

Duration: “instant”
Example

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

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

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

curl http://10.0.2.1/api/v2/backup/get > backup.json

/api/v2/backup/set (POST) -- Restore a configuration backup

Request

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

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

curl -i http://10.0.2.1/api/v2/backup/set -X POST -H "Content-Type: application/json"
-d @backup.json

Create your own Knowledge Base