All high performance SBG Systems Inertial Navigation Systems (INS) can be configured and interfaced using an easy to use RESTful API. This powerful API allows any developer to configure the device, execute specific actions such as starting/stopping the data logger and retrieve the device status.

This API however is not designed to return high frequency IMU or INS measurements and the sbgECom binary logs should be used instead.

The best example to illustrate what this API can be used for is the web interface embedded in SBG Systems' INS. This web interface relies only on this RESTful API to display the device status, allow the user configure the unit and access specific functions such as the data logger or the EKF Auto calibration module.

This RESTful API can be accessed through a traditional HTTP client/server scheme but also through a serial (UART) connection using sbgECom if the host has no Ethernet capabilities.

This document contains all paths and schemas implemented and supported by SBG Systems Inertial Navigation Systems (INS) RESTful API.

Each API endpoint in this documentation is described using several parts:

• The HTTP method. Includes GET (reading data) and POST (modifying data or executing an action)
• The base path. It's your device IP address or name such as http://ekinox_045000005.local It goes before the endpoint path.
• The endpoint path. For example, /settings/default to restore the device default settings.
• Required parameters. These parameters must be included in a request otherwise the request will fail.
• Optional parameters. These parameters can be included in a request and if not the value will not be updated keeping the old one.
• Code examples. Each endpoint has example requests in cURL format and sbgECom library written in C.

This API provides a simple user authentication mechanism to restrict access to certain actions such as changing the device's settings. For instance, a survey operator should be able to start and stop the data logger, monitor the device and download acquired log files. However, he shouldn't change the device settings or update the device firmware.

It is also very interesting for OEM integrators to have a full access to setup the unit over a serial connection but avoid a end user to change the device settings through the device embedded web interface.

Finally, some users don't want to bother at all with access rights and users management with a full access to all actions without any login step.

All these scenarios are perfectly handled by this API using a simple user database with an associated use role.

SBG Systems' INS have a pre-defined list of users with associated access rights that can't be changed. However, for each user, you can change the default password that is empty when you receive your unit.

The table below lists all available users and if a default password is set:

The table below details for each user the associated pre-defined access rights:

All user related operations such as login, logout and password change are available in the User Section.

When a user is successfully logged in, a unique AUTH_TOKEN is generated and returned in the JSON response body. This AUTH_TOKEN, that is basically a string, should then be used in each subsequent request to identify the user.

This REST API only supports URL parameter method to provide this AUTH_TOKEN as shown in the example below. HTTP header based methods are not supported at all to ease sbgECom C implementation support.

http://ekinox_045000005.local/api/v1/reboot?auth=AUTH_TOKEN

Default User

The default user is automatically selected by the unit at startup. It's the user with the highest role that has no password.

For instance, if the operator has a password but the setup has no password, the default user will be setup. An other example, if both the operator and setup have a password, the default user will be viewer.

If no authorization token is provided in URLs auth parameter, the API automatically fallbacks to the default user. This way, if you are not interested in access right management, you can just leave the default empty password and don't provide any auth URL parameter.

Power On/Reboot

After a power on or following a device reset, no user is logged in and any previously obtained AUTH_TOKEN is not valid anymore. For instance, if you were logged in as a setup user and execute a device reboot, you will have to redo the login process if you still need setup access rights.

However, to improve the user experience, SBG Systems' INS web interfaces have an auto login feature. The login credentials are stored locally in the browser so if you change the device settings and the device has to reboot, the web interface will automatically redo the login process once the device is ready. This way you don't have to enter twice your user name and user password.

By default, only the factory user account has a pre-defined password set that is only known by SBG Systems. All other user accounts have no password meaning you have access to setup rights without requiring any login process.

To start using access rights, you should thus first set a password to user accounts to restrict permissions on the product.

Changing user password

Any logged user can change his password at any time. However, only the setup user can change other users' password.

To change a password, you should be successfully logged in using the route user/login and then you can use the route user/password with the AUTH_TOKEN returned during the login process to update the user password.

Remove a user password

If you would like to clear a user password, you just have to provide an empty password in the route user/password.

When used as a traditional RESTful API, only HTTP connections are supported and not HTTPS. An HTTP connection transmit all information in plain text so it's easy to intercept data between the server (the INS) and the client (the web interface). This type of 'attacks' is called a main-in-the-middle.

It's not a big concern for an INS as no sensitive information is transmitted except the user login and user password if you have set one. On the other hand use HTTPS connections raise a lot of complicated issues and concerns related to SSL certificates and as of today there is no good solution that doesn't impact negatively the user experience.

SBG Systems consequently recommends you don't use a sensitive user password as it could be relatively easy for an attacker to spy the password during login or password change operations.

This API only uses two HTTP methods to either retrieve resources or execute actions:

• The GET method is used to retrieve a representation of a resource. If successful, GET returns a representation in JSON and an HTTP response code of 200 (OK). In an error case, it most often returns a 404 (NOT FOUND) or 400 (BAD REQUEST). The GET method never modify any resource or state on the server.
• The POST method is used to update resources (device settings) or to execute actions (device reboot). On successful update or action, a HTTP status code 200 (OK) is returned with a JSON body detailing the operation status. In case of error the corresponding HTTP status code is returned such as 400 (Bad Request).

All over HTTP verbs such as PUT, PATCH or DELETE are not supported by the server to keep things simple.

This API uses standard HTTP status codes to report either a success or a failure. A success is only reported by the status code 200 and the response body always contains the requested resource or the result of an action using JSON.

All other status codes are used to report an error and the response body always contains a JSON detailing the error.

The table below list all HTTP response status codes used by the API.

It indicates that the REST API successfully carried out whatever action the client requested.

The 200 response includes always a response body. The information returned with the response is dependent on the method used in the request, for example:

• GET an entity corresponding to the requested resource is sent in the response;
• POST an entity describing or containing the result of the action;

400 is the generic client-side error status, used when no other 4xx error code is appropriate. Errors can be like malformed request syntax, invalid request message format, or deceptive request routing etc.

The client SHOULD NOT repeat the request without modifications.

A 401 error response indicates that the client tried to operate on a protected resource without providing the proper authorization. It may have provided the wrong credentials or none at all. The response must include a WWW-Authenticate header field containing a challenge applicable to the requested resource.

The client MAY repeat the request with a suitable authorization token in the path parameter. If the request already included authorization credentials, then the 401 response indicates that authorization has been refused for those credentials.

A 403 error response indicates that the client’s request is formed correctly, but the REST API refuses to honor it, i.e., the user does not have the necessary permissions for the resource. A 403 response is not a case of insufficient client credentials; that would be 401 (“Unauthorized”).

Authentication will not help, and the request SHOULD NOT be repeated. Unlike a 401 Unauthorized response, authenticating will make no difference.

The 404 error status code indicates that the REST API can’t map the client’s URI to a resource but may be available in the future. Subsequent requests by the client are permissible.

No indication is given of whether the condition is temporary or permanent. This status code is commonly used when the server does not wish to reveal exactly why the request has been refused, or when no other response is applicable.

A 409 status code indicates that the request is in conflict with the current state of the target resource. However, the user might be able to resolve the conflict and resubmmit the request.

This code is for instance used if a user would like to modify the device settings while an other one is already doing so.

The 422 response status code indicates that the server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions. It's probably due to invalid input parameters such as in invalid enum value.

The client SHOULD NOT repeat the request without modifications.

500 is the generic REST API error response. Most web frameworks automatically respond with this response status code whenever they execute some request handler code that raises an exception.

A 500 error is never the client’s fault, and therefore, it is reasonable for the client to retry the same request that triggered this response and hope to get a different response.

The API response is the generic error message, given when an unexpected condition was encountered and no more specific message is suitable.

SBG Systems provides two way to access this RESTful API. Either using a traditional HTTP client/server implementation like for any REST API or by using the sbgECom C library that is able to transport the JSON content API other a standard serial (UART) connection.

This RESTful API has been designed to configure the device, execute specific actions such as starting/stopping the data logger and can also be used to return some status on the INS.

It's recommended you have already review the sbgECom C library documentation before you continue reading this document.

This REST API exposes resources and actions URLs also called paths. It returns HTTP response codes to indicate a success or an error. The API accepts and returns JSON payloads in the HTTP body. Only HTTP connections are accepted on standard port 80.

You can use your favorite HTTP/REST library for your programming language to use this API.

This example shows how to enable the SBG_ECOM_LOG_EKF_NAV message (ekfNav) at 100 Hz using only curl command line tool. Two methods are presented to illustrate how it is easy to change only specific configurations.

You can either use a POST method on the general settings path with a JSON payload containing only the settings you would like to update:

curl  --request POST \
      --url http://ekinox_023000029.local/api/v1/settings?auth=QSZXHDPG3J \
      --header 'Accept: application/json' \
      --header 'Content-Type: application/json' \
      --data '{"output":{"comA":{"messages":{"ekfNav":"10ms"}}}}'

Or you can point directly to the settings you would like to change as shown below:

curl  --request POST \
      --url http://ekinox_023000029.local/api/v1/settings/output/comA/messages/ekfNav?auth=QSZXHDPG3J \
      --header 'Accept: application/json' \
      --header 'Content-Type: application/json' \
      --data '"10ms"'

If you would like to setup your INS with a serial connection, SBG Systems provides the open source sbgECom C library. The sbgECom C library can be used to access all the REST API features as well as all binary output logs such as SBG_ECOM_LOG_EKF_NAV.

This example below, enables the SBG_ECOM_LOG_EKF_NAV message over the serial port B using two different methods as for the HTTP example.

You can for example use the general settings path and only provide in the JSON request the settings you would like to change. You will have to send the JSON below to change only the imuShort message on COM A.

{
  "output": {
    "comA" : {
      "messages": {
        "ekfNav": "10ms"
      }
    }
  }
}

This JSON will then have to be sent using sbgECom on the settings path as shown below:

// We consider the sbgECom has been correction initialized
errorCode = sbgEComCmdApiPost(&protocol, "settings", "auth=QSZXHDPG3J", "{\"output\":{\"comA\":{\"messages\":{\"ekfNav\":\"10ms\"}}}}", &httpResponse);

Or you can also directly use the final end point as demonstrated in the example below:

// We consider the sbgECom has been correction initialized
errorCode = sbgEComCmdApiPost(&protocol, "settings/output/comA/messages/ekfNav", "auth=QSZXHDPG3J", "\"onChange\"", &httpResponse);

SBG Systems has developed a command line tool (CLI) to let you configure your unit with no development.

This CLI tool uses the sbgECom to let you access from a command line all GET and POST methods from this API. You

This example below, enables the SBG_ECOM_LOG_EKF_NAV message over the serial port B using two different methods as for the HTTP example.

$ ./build/bin/sbgEComApi -s /dev/ttyUSB0 -r 921600 -p settings/output/comA/messages/ekkNav -b "onChange"

This API has been designed to be as easy to use as possible.

We have however written some step by step guides so you can start using it in no time.

Click here to visit our API Guide Tutorial.

SBG Systems tries to avoid as much as possible evolutions that might break user code integration. However, this API intends to be updated with improvements, new features and much more.

A REST API, based on JSON files, is by design, much more resilient to future evolutions. If correctly implemented by the host application, a lot of changes can be made in the API without breaking the compatibility.

As for any REST API, there are two types of API evolutions:

• Changes that are backward compatibles: Adding a new field in a json payload or a new path.
• Changes that might break the compatibility: Removing a path or updating completely an existing path payload schema.

This API is versioned using a Major.Minor.Build-Qualifier information. Only the Major and Minor fields are of interest for API compatibility. Any backward compatible modification is identified by a Minor evolution.

If an API evolution breaks the backward compatibility, this change is indicated by a Major increment. This is also reflected in the API path that contains the Major version (api/v1/... or api/v2/...).

When a new Major API is introduced, the previous versions will still be available to maintain existing integration compatibility. For example, if the api/v1/info path is renamed with a completely new payload schema to whoAmI, it should be made available at the path api/v2/whoAmI However, you should still be able to query the path api/v1/info to get the legacy response.

Each time a new API release is issued, the version number is updated and a detailed change log is provided in this documentation.

You can also easily retrieve the full API version indication in use by your product with the api/v1/info path. Please refer to path info endpoint for more details.

Please find below the list of changes for each API release.

• [INSAPI-117] - REST API: Add a path to return SV status & info
• [INSAPI-125] - Update api/v1/status documentation with EKF smart position
• [INSAPI-126] - Added a "Railway" motion profile for train applications
• [INSAPI-129] - Add support to request CAN log availability based on device features
• [INSAPI-131] - Add a new PSBGA NMEA message that output the INS attitude
• [INSAPI-132] - Add supported API version to the device information

• [INSAPI-108] - Improve clock selection documentation
• [INSAPI-127] - Update api/v1/firmware path documentation and state machine

• [INSAPI-123] - Fix the REST API link to step by step getting started guide
• [INSAPI-124] - Remove the last dot for mDNS based urls
• [INSAPI-130] - Fixed settings/ports example syntax issue

• [INSAPI-119] - Add pedestrian and UAV motion profiles
• [INSAPI-121] - Add support for the Teledyne Wayfinder DVL protocol
• [INSAPI-115] - Add option to control SSL/TLS encryption with NTRIP
• [INSAPI-116] - Add documentation about querying a list of NTRIP mountpoints

• [INSAPI-111] - Fix device available feature checks when updating settings
• [INSAPI-107] - Fix data type for initial GPS leap seconds settings value

All the device settings can be read and changed from this API. For example, all SBG Systems units use this API to change and read the configuration.

The API also provides some commands to restore default settings and import/export settings from JSON files. Finally, a basic lock/unlock mechanism is also present to nicely prevent settings concurrent editions.