Skip to main content
Skip table of contents

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

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.