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 or php 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",
      "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 -i "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/log/record (POST) -- Log recording

• Request

  CODE

  {
      "action": "start",     // "start", "stop", "status"
      "disk":   "internal",  // "internal", "external" (only for action=start)
      "level":  "maximal",   // "minimal", "medium", "maximal" (only for action=start)
  }

• Response

  CODE

  {
      "_ok": true, "_message": "...",
      "state":    "recording",                   // "recording", "stopped"
      // And if state is recording:
      "name":     "2022-12-27-20-36-24_minimal", // Name of recording
      "size":     162181207,                     // Size of recording [bytes]
      "duration": 815,                           // Duration of recording [s]
      "disk":     "internal",
      "level":    "minimal"
  }

• Duration: Start and stop actions may take a while, status is "instant"

• Examples

  CODE

  curl -i http://10.0.2.1/api/v2/log/record -X POST -H "Content-Type: application/json" \
      -d '{"action":"start","disk":"internal","level":"minimal"}'
  curl -i http://10.0.2.1/api/v2/log/record -X POST -H "Content-Type: application/json" \
      -d '{"action":"status"}'

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

ROS params

/api/v2/params/config/get (GET) -- Get current configuration (a.k.a. customer config) 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 parameters

• 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 parameters

• 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