LiDAR: Headless configuration deployment

1 - Overview

The REST API is a JSON-based interface served over plain HTTP on port 80 of the sensor. It provides a uniform way to read and write device parameters and trigger actions.

The configuration file feature lets you:

• Archive a complete device configuration as a single file.
• Clone a configuration to multiple sensors of the same type.
• Roll back to a known-good state after an unintended change.
• Exchange configurations between devices.

The device requires a valid session token in the X-Session-Token HTTP header when downloading or uploading a configuration file. The token is obtained via POST /api/CreateSessionToken and is bound to the user level that was authenticated when the token was created.

2 - Session Token Authentication

The device uses HTTP Basic Authentication to establish the user level for every request. Current firmware additionally requires a short-lived session token for the GET /api/parameterbackup and PUT /api/parameterbackup endpoints. This prevents cross-site request forgery on the raw file endpoints.

2.1  Obtaining a session token

Send a POST /api/CreateSessionToken request with valid Basic Auth credentials. The device returns a short-lived opaque token string. All subsequent requests to the /api/parameterbackup endpoints must include this token in the X-Session-Token header.

Request - create session token:

POST http://<device-ip>/api/CreateSessionToken
Authorization: Basic <base64(username:password)>
Content-Type: application/json

{}

Response (HTTP 200):

{
  "header": { "status": 0, "message": "Ok" },
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsIn..."
  }
}

2.2  Using the token

Include the token as a custom HTTP header on every request to /api/parameterbackup:

X-Session-Token: eyJhbGciOiJIUzI1NiIsIn...

3 - API Endpoints

3.1  REST API actions (POST)

3.2  File transfer endpoints (GET / PUT)

3.3  CreateParameterBackup request payload

POST http://<device-ip>/api/CreateParameterBackup
Authorization: Basic <base64(username:password)>
Content-Type: application/json

{
  "data": {
    "Passphrase": "your-passphrase"
  }
}

The Passphrase protects the configuration file. The same passphrase must be supplied when importing. It is not the device login password; it is an independent value you choose for the configuration file.

3.4  RestoreParameterBackup request payload

POST http://<device-ip>/api/RestoreParameterBackup
Authorization: Basic <base64(username:password)>
Content-Type: application/json

{
  "data": {
    "Passphrase": "your-passphrase"
  }
}

4 - Download Configuration File: step by step

5 - Import Configuration File: step by step

6 - Pseudocode

The following language-neutral pseudocode shows both workflows end to end. Replace http_post, http_get, and http_put with the HTTP client of your choice.

6.1  Download a configuration file

// 1. Obtain session token
response = http_post(
    url     = "http://<device-ip>/api/CreateSessionToken",
    headers = { "Authorization": basic_auth("Service", "<password>") },
    body    = "{}"
)
token = response.json["data"]["token"]

// 2. Trigger configuration file creation
http_post(
    url     = "http://<device-ip>/api/CreateParameterBackup",
    headers = { "Authorization": basic_auth("Service", "<password>") },
    body    = '{ "data": { "Passphrase": "your-passphrase" } }'
)

// 3. Wait for async operation to complete
sleep(1000 ms)

// 4. Download the configuration file
response = http_get(
    url     = "http://<device-ip>/api/parameterbackup",
    headers = {
        "Authorization":   basic_auth("Service", "<password>"),
        "X-Session-Token": token
    }
)
assert response.status == 200
write_file("parameterbackup.json", response.body)

6.2  Import (upload and restore) a configuration file

// 1. Obtain session token (or reuse existing one if still valid)
response = http_post(
    url     = "http://<device-ip>/api/CreateSessionToken",
    headers = { "Authorization": basic_auth("Service", "<password>") },
    body    = "{}"
)
token = response.json["data"]["token"]

// 2. Upload the configuration file
config_data = read_file("parameterbackup.json")
response = http_put(
    url     = "http://<device-ip>/api/parameterbackup",
    headers = {
        "Authorization":   basic_auth("Service", "<password>"),
        "X-Session-Token": token,
        "Content-Type":    "application/octet-stream"
    },
    body    = config_data
)
assert response.status == 200

// 3. Trigger the import
http_post(
    url     = "http://<device-ip>/api/RestoreParameterBackup",
    headers = { "Authorization": basic_auth("Service", "<password>") },
    body    = '{ "data": { "Passphrase": "your-passphrase" } }'
)

// 4. Wait for async operation to complete
sleep(1000 ms)

// 5. Verify - read back a parameter
response = http_get(
    url     = "http://<device-ip>/api/LocationName",
    headers = { "Authorization": basic_auth("Service", "<password>") }
)
print("LocationName =", response.json["data"]["LocationName"])

7 - Error handling and troubleshooting