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

  CODE

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

  CODE

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

  CODE

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

  CODE

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

  CODE

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

  CODE

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

  CODE

  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

  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

  CODE

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

  CODE

  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

  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

  CODE

  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

  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

  CODE

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

  CODE

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

  CODE

  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

  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

  CODE

  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

  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

  CODE

  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

  CODE

  {
      "which": "mapbox"
  }

• Response

  CODE

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

• Duration: "instant"

• Example

  CODE

  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

  CODE

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

• Response

  CODE

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

• Duration: "instant"

• Example

  CODE

  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

  CODE

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

• Response

  CODE

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

• Duration: "instant"

• Example

  CODE

  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

  CODE

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

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

• Example

  CODE

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

  CODE

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

  CODE

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

  CODE

  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

  CODE

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

• Response

  CODE

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

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

• Example

  CODE

  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

  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

  CODE

  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

  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

  CODE

  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

  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

  CODE

  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

  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

  CODE

  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

  CODE

  {
      "ssid": "guguseli"
  }

• Response

  CODE

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

• Duration: "instant"

• Example

  CODE

  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

  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

  CODE

  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

  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

  CODE

  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

  CODE

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

• Duration: "instant"

• Examples

  CODE

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

/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

  CODE

  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

  CODE

  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

  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

  CODE

  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

  CODE

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

• Response

  CODE

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

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

• Example

  CODE

  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

  CODE

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

  CODE

  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

  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

  CODE

  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

  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

  CODE

  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

  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

  CODE

  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

  CODE

  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

  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

  CODE

  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

  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

  CODE

  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

  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

  CODE

  curl -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 or external:

  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

  CODE

  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!

• 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

  CODE

  curl -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 from stopping to stopped 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

  CODE

  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

  CODE

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

• Response

  CODE

  {
      "_ok": true, "_message": "...",
      "stationary": "missing",          // "present", "missing"
      "warmstart":  "present",
  }

• Duration: "instant"

• Example

  CODE

  curl -i http://10.0.2.1/api/v2/fusion/data -X POST -H "Content-Type: application/json" \
      -d '{"stationary":"remove"}'

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

  CODE

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

  CODE

  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

  CODE

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

• Response

  CODE

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

• Duration: "instant"

• Example

  CODE

  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

  CODE

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

• Duration: "instant"

• Example

  CODE

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

  CODE

  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

  CODE

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

• Duration: "instant"

• Example

  CODE

  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

  CODE

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

• Response

  CODE

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

• Duration: "instant"

• Example

  CODE

   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

  CODE

  {
      "reset": "default"
  }

• Response

  CODE

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

• Duration: "instant"

• Example

  CODE

   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

  CODE

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

• Duration: "instant"

• Example

  CODE

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

  CODE

  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

  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

  CODE

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

  CODE

  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

  CODE

  {
      "reset": "default"
  }

• Response

  CODE

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

• Duration: “instant”

• Example

  CODE

  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.

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

  CODE

  curl 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

  CODE

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