System and logs¶
The following resources and requests expose the rc_cube’s system-level API. They enable
- access to log files (system-wide or module-specific)
- access to information about the device and run-time statistics such as date, MAC address, clock-time synchronization status, and available resources;
- management of installed software licenses; and
- the rc_cube to be updated with a new firmware image.
-
GET
/logs
¶ Get list of available log files.
Template request
GET /api/v2/logs HTTP/1.1
Sample response
HTTP/1.1 200 OK Content-Type: application/json [ { "date": 1503060035.0625782, "name": "rcsense-api.log", "size": 730 }, { "date": 1503060035.741574, "name": "stereo.log", "size": 39024 }, { "date": 1503060044.0475223, "name": "camera.log", "size": 1091 } ]
Response Headers: - Content-Type – application/json application/ubjson
Status Codes: - 200 OK – successful operation (returns array of LogInfo)
Referenced Data Models:
-
GET
/logs/{log}
¶ Get a log file. Content type of response depends on parameter ‘format’.
Template request
GET /api/v2/logs/<log>?format=<format>&limit=<limit> HTTP/1.1
Sample response
HTTP/1.1 200 OK Content-Type: application/json { "date": 1581609251.8168414, "log": [ { "component": "rc_gev_server", "level": "INFO", "message": "Application from IP 10.0.1.7 registered with control access.", "timestamp": 1581609249.61 }, { "component": "rc_gev_server", "level": "INFO", "message": "Application from IP 10.0.1.7 deregistered.", "timestamp": 1581609249.739 }, { "component": "rc_gev_server", "level": "INFO", "message": "Application from IP 10.0.1.7 registered with control access.", "timestamp": 1581609250.94 }, { "component": "rc_gev_server", "level": "INFO", "message": "Application from IP 10.0.1.7 deregistered.", "timestamp": 1581609251.819 } ], "name": "gev.log", "size": 42112 }
Parameters: - log (string) – name of the log file (required)
Query Parameters: - format (string) – return log as JSON or raw (one of
json
,raw
; default:json
) (optional) - limit (integer) – limit to last x lines in JSON format (default:
100
) (optional)
Response Headers: - Content-Type – text/plain application/json
Status Codes: - 200 OK – successful operation (returns Log)
- 404 Not Found – log not found
Referenced Data Models:
-
GET
/system
¶ Get system information on device.
Template request
GET /api/v2/system HTTP/1.1
Sample response
HTTP/1.1 200 OK Content-Type: application/json { "dns": { "dns_servers": [ "10.0.0.1", "1.1.1.1" ], "manual_dns_servers": [ "1.1.1.1" ] }, "dongle_id": "dinkey:1234", "firmware": { "active_image": { "image_version": "22.04.0" }, "fallback_booted": false, "inactive_image": { "image_version": "22.01.0" }, "next_boot_image": "active_image" }, "hostname": "rc-cube-00012e96ef39", "link_speed": 1000, "mac": "00:01:2e:96:ef:39", "model_name": "rc_cube S", "network": { "current_method": "DHCP", "default_gateway": "10.0.3.254", "ip_address": "10.0.2.40", "settings": { "dhcp_enabled": true, "persistent_default_gateway": "", "persistent_ip_address": "192.168.0.111", "persistent_ip_enabled": false, "persistent_subnet_mask": "255.255.255.0" }, "subnet_mask": "255.255.252.0" }, "ntp_status": { "accuracy": "0.000032666 seconds slow of NTP time", "synchronized": true }, "pipelines": { "config": { "0": { "type": "rc_visard" }, "1": { "type": "rc_visard" } }, "max_pipelines": 2, "pending_changes": false }, "ptp_status": { "master_ip": "", "offset": 0, "offset_dev": 0, "offset_mean": 0, "state": "off" }, "ready": true, "reboot_required": false, "sensor_interfaces": { "sensor0": { "link_speed": 2500 } }, "serial": "00012e96ef39", "time": 1649678734.0306993, "uptime": 336455.25, "userspace": { "available": true, "enabled": true } }
Response Headers: - Content-Type – application/json application/ubjson
Status Codes: - 200 OK – successful operation (returns SysInfo)
Referenced Data Models:
-
GET
/system/backup
¶ Get backup.
Template request
GET /api/v2/system/backup?pipelines=<pipelines>&load_carriers=<load_carriers>®ions_of_interest=<regions_of_interest>&grippers=<grippers> HTTP/1.1
Query Parameters: - pipelines (boolean) – backup pipelines with node settings, i.e. parameters and preferred_orientation (default:
True
) (optional) - load_carriers (boolean) – backup load_carriers (default:
True
) (optional) - regions_of_interest (boolean) – backup regions_of_interest (default:
True
) (optional) - grippers (boolean) – backup grippers (default:
True
) (optional)
Response Headers: - Content-Type – application/json application/ubjson
Status Codes: - 200 OK – successful operation
- pipelines (boolean) – backup pipelines with node settings, i.e. parameters and preferred_orientation (default:
-
POST
/system/backup
¶ Restore backup.
Template request
POST /api/v2/system/backup HTTP/1.1 Accept: application/json application/ubjson {}
Sample response
HTTP/1.1 200 OK Content-Type: application/json { "return_code": { "message": "backup restored", "value": 0 }, "warnings": [] }
Request JSON Object: - backup (object) – backup data as json object (required)
Request Headers: - Accept – application/json application/ubjson
Response Headers: - Content-Type – application/json application/ubjson
Status Codes: - 200 OK – successful operation
-
GET
/system/disk_info
¶ Get disk space info
Template request
GET /api/v2/system/disk_info HTTP/1.1
Response Headers: - Content-Type – application/json application/ubjson
Status Codes: - 200 OK – successful operation
-
GET
/system/dns
¶ Get DNS settings.
Template request
GET /api/v2/system/dns HTTP/1.1
Sample response
HTTP/1.1 200 OK Content-Type: application/json { "dns": { "dns_servers": [ "10.0.0.1", "1.1.1.1" ], "manual_dns_servers": [ "1.1.1.1" ] } }
Response Headers: - Content-Type – application/json application/ubjson
Status Codes: - 200 OK – successful operation (returns DNS)
Referenced Data Models:
-
PUT
/system/dns
¶ Set manual DNS servers.
Template request
PUT /api/v2/system/dns HTTP/1.1 Accept: application/json application/ubjson {}
Sample response
HTTP/1.1 200 OK Content-Type: application/json { "dns": { "dns_servers": [ "10.0.0.1", "1.1.1.1" ], "manual_dns_servers": [ "1.1.1.1" ] } }
Request JSON Object: - manual_dns_servers (ManualDNSServers) – Manual DNS servers (required)
Request Headers: - Accept – application/json application/ubjson
Response Headers: - Content-Type – application/json application/ubjson
Status Codes: - 200 OK – successful operation (returns DNS)
- 400 Bad Request – invalid/missing arguments
Referenced Data Models:
-
GET
/system/license
¶ Get information about licenses installed on device.
Template request
GET /api/v2/system/license HTTP/1.1
Sample response
HTTP/1.1 200 OK Content-Type: application/json { "components": { "hand_eye_calibration": true, "rectification": true, "stereo": true }, "valid": true }
Response Headers: - Content-Type – application/json application/ubjson
Status Codes: - 200 OK – successful operation (returns LicenseInfo)
Referenced Data Models:
-
POST
/system/license
¶ Update license on device with a license file.
Template request
POST /api/v2/system/license HTTP/1.1 Accept: multipart/form-data
Form Parameters: - file – license file (required)
Request Headers: - Accept – multipart/form-data
Status Codes: - 200 OK – successful operation
- 400 Bad Request – not a valid license
-
GET
/system/network
¶ Get current network configuration.
Template request
GET /api/v2/system/network HTTP/1.1
Sample response
HTTP/1.1 200 OK Content-Type: application/json { "current_method": "DHCP", "default_gateway": "10.0.3.254", "ip_address": "10.0.1.41", "settings": { "dhcp_enabled": true, "persistent_default_gateway": "", "persistent_ip_address": "192.168.0.10", "persistent_ip_enabled": false, "persistent_subnet_mask": "255.255.255.0" }, "subnet_mask": "255.255.252.0" }
Response Headers: - Content-Type – application/json application/ubjson
Status Codes: - 200 OK – successful operation (returns NetworkInfo)
Referenced Data Models:
-
GET
/system/network/settings
¶ Get current network settings.
Template request
GET /api/v2/system/network/settings HTTP/1.1
Sample response
HTTP/1.1 200 OK Content-Type: application/json { "dhcp_enabled": true, "persistent_default_gateway": "", "persistent_ip_address": "192.168.0.10", "persistent_ip_enabled": false, "persistent_subnet_mask": "255.255.255.0" }
Response Headers: - Content-Type – application/json application/ubjson
Status Codes: - 200 OK – successful operation (returns NetworkSettings)
Referenced Data Models:
-
PUT
/system/network/settings
¶ Set current network settings.
Template request
PUT /api/v2/system/network/settings HTTP/1.1 Accept: application/json application/ubjson {}
Sample response
HTTP/1.1 200 OK Content-Type: application/json { "dhcp_enabled": true, "persistent_default_gateway": "", "persistent_ip_address": "192.168.0.10", "persistent_ip_enabled": false, "persistent_subnet_mask": "255.255.255.0" }
Request JSON Object: - settings (NetworkSettings) – network settings to apply (required)
Request Headers: - Accept – application/json application/ubjson
Response Headers: - Content-Type – application/json application/ubjson
Status Codes: - 200 OK – successful operation (returns NetworkSettings)
- 400 Bad Request – invalid/missing arguments
- 403 Forbidden – Changing network settings forbidden because this is locked by a running GigE Vision application.
Referenced Data Models:
-
PUT
/system/reboot
¶ Reboot the device.
Template request
PUT /api/v2/system/reboot HTTP/1.1
Status Codes: - 200 OK – successful operation
-
GET
/system/rollback
¶ Get information about currently active and inactive firmware/system images on device.
Template request
GET /api/v2/system/rollback HTTP/1.1
Sample response
HTTP/1.1 200 OK Content-Type: application/json { "active_image": { "image_version": "rc_cube_v1.1.0" }, "fallback_booted": false, "inactive_image": { "image_version": "rc_cube_v1.0.0" }, "next_boot_image": "active_image" }
Response Headers: - Content-Type – application/json application/ubjson
Status Codes: - 200 OK – successful operation (returns FirmwareInfo)
Referenced Data Models:
-
PUT
/system/rollback
¶ Rollback to previous firmware version (inactive system image).
Template request
PUT /api/v2/system/rollback HTTP/1.1
Status Codes: - 200 OK – successful operation
- 400 Bad Request – already set to use inactive partition on next boot
- 500 Internal Server Error – internal error
-
GET
/system/time
¶ Get system time in UTC as string with format “YYYY-MM-DD hh:mm:ss”
Template request
GET /api/v2/system/time HTTP/1.1
Sample response
HTTP/1.1 200 OK Content-Type: application/json { "utc": "2023-10-05 08:35:26" }
Response Headers: - Content-Type – application/json application/ubjson
Status Codes: - 200 OK – successful operation
-
PUT
/system/time
¶ Set system time in UTC as string with format “YYYY-MM-DD hh:mm:ss”
Template request
PUT /api/v2/system/time?utc=<utc> HTTP/1.1
Sample response
HTTP/1.1 200 OK Content-Type: application/json { "utc": "2023-10-05 08:35:26" }
Query Parameters: - utc (string) – Time in UTC as string with format “YYYY-MM-DD hh:mm:ss” (required)
Response Headers: - Content-Type – application/json application/ubjson
Status Codes: - 200 OK – successful operation
- 400 Bad Request – invalid/missing arguments
- 403 Forbidden – Changing time forbidden because time is synchronized via NTP or PTP.
-
GET
/system/ui_lock
¶ Get UI lock status.
Template request
GET /api/v2/system/ui_lock HTTP/1.1
Sample response
HTTP/1.1 200 OK Content-Type: application/json { "enabled": false }
Response Headers: - Content-Type – application/json application/ubjson
Status Codes: - 200 OK – successful operation (returns UILock)
Referenced Data Models:
-
DELETE
/system/ui_lock
¶ Remove UI lock.
Template request
DELETE /api/v2/system/ui_lock HTTP/1.1
Sample response
HTTP/1.1 200 OK Content-Type: application/json { "enabled": false, "valid": false }
Response Headers: - Content-Type – application/json application/ubjson
Status Codes: - 200 OK – successful operation
-
POST
/system/ui_lock
¶ Verify or set UI lock.
Template request
POST /api/v2/system/ui_lock?hash=<hash>&set=<set> HTTP/1.1
Sample response
HTTP/1.1 200 OK Content-Type: application/json { "enabled": true, "valid": true }
Query Parameters: - hash (string) – hash of the UI lock password (required)
- set (boolean) – set new hash instead of veryfing (optional)
Response Headers: - Content-Type – application/json application/ubjson
Status Codes: - 200 OK – successful operation
-
GET
/system/update
¶ Get information about currently active and inactive firmware/system images on device.
Template request
GET /api/v2/system/update HTTP/1.1
Sample response
HTTP/1.1 200 OK Content-Type: application/json { "active_image": { "image_version": "rc_cube_v1.1.0" }, "fallback_booted": false, "inactive_image": { "image_version": "rc_cube_v1.0.0" }, "next_boot_image": "active_image" }
Response Headers: - Content-Type – application/json application/ubjson
Status Codes: - 200 OK – successful operation (returns FirmwareInfo)
Referenced Data Models:
-
POST
/system/update
¶ Update firmware/system image with a mender artifact. Reboot is required afterwards in order to activate updated firmware version.
Template request
POST /api/v2/system/update HTTP/1.1 Accept: multipart/form-data
Form Parameters: - file – mender artifact file (required)
Request Headers: - Accept – multipart/form-data
Status Codes: - 200 OK – successful operation
- 400 Bad Request – client error, e.g. no valid mender artifact