web
You’re offline. This is a read only version of the page.
close
Support Portal

Application /Product Knowledge

LiDAR: Headless firmware deployment

Article No: KA-10732
Version: 1.2
Subject to change without notice
Upload a firmware package and execute the flash sequence on the device using the HTTP REST API without any physical access.
Related Products
picoScan100

Table of Contents

Firmware Always download the latest firmware package for your device variant from the SICK product pag.
OpenAPI Update state schema is shipped in the OpenAPI specification.
Overview

1 - Overview

Firmware updates are performed over HTTP using a five-step sequence. The steps must be followed in order: skipping or reordering them can leave the device in an inconsistent state.

After the flash is complete the device reboots automatically. During the reboot period it is unreachable on the network. The update is considered successful only after the device comes back online and the reported firmware version matches the expected value.

Package Types

2 - Firmware Package Types

File extension Type Device requirement
.spk Unsigned package Compatible with firmware version < V2.2.0
.spk.signed Signed package (secure boot) Requires device firmware ≥ V2.2.0
Update Sequence

3 - Five-Step Update Sequence

1
Authenticate - obtain a session token

Send POST /api/CreateSessionToken with Basic Auth at Service level. Store the returned token; it is required in the X-Session-Token header for the upload request. 

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

{}
// Response
{
  "header": { "status": 0, "message": "Ok" },
  "data": { "token": "eyJhbGci..." }
}
2
Upload the firmware package

Send PUT /api/update with the firmware file as binary body. Include both Basic Auth and the session token. 

PUT http://<device-ip>/api/update
Authorization: Basic <base64(Service:<password>)>
X-Session-Token: <token>
Content-Type: application/octet-stream

<binary firmware file content>

A 200 OK response confirms the package was received.

3
Trigger the flash operation

After the upload completes trigger the flash process by sending: 

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

{}
4
Poll the update state

Query GET /api/UpdateState every 5 s until the state reaches Finished (2) or the device becomes unreachable (indicating a reboot has started). Stop on Error (3) and investigate before retrying. 

GET http://<device-ip>/api/UpdateState

// Response
{
  "header": { "status": 0, "message": "Ok" },
  "data": { "UpdateState": 1 }
}

See §4 for the full state table.

5
Verify the new firmware version

After the device comes back online, read the firmware version and confirm it matches the expected value: 

GET http://<device-ip>/api/DeviceIdent

// Response
{
  "header": { "status": 0, "message": "Ok" },
  "data": { "Name": "...", "Version": "2.3.0.0R" }
}
Reference

4 - UpdateState Values

Value State Meaning
0 Initial No update in progress. Package may have been uploaded but flash has not started.
1 Started Flashing in progress. Do not power-cycle the device.
2 Finished Flash complete. The device will reboot automatically.
3 Error Update failed. Check package compatibility and retry. Do not power-cycle immediately.
Do not power-cycle during state 1 (Started) Wait for state 2 or state 3 before taking any further action.
Error Handling

5 - Error Handling

Condition Likely cause Action
UpdateState stays at 0 after trigger Signed package rejected or trigger not received Check package type (see §2). Re-send RunFirmwareUpdate.
UpdateState = 3 (Error) Package incompatible, corrupted, or wrong device variant Verify the package is for this device model and firmware path. Re-download and retry.
Device unreachable during poll Device is rebooting after a successful flash Normal. Wait up to 60 s and then poll GET /api/DeviceIdent until the device responds.
Device does not come back after reboot Network issue or boot failure Check physical network connection.
PUT /api/update returns 401 Missing or expired session token Obtain a new session token via CreateSessionToken and retry.
Pseudocode

6 - End-to-End Pseudocode

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

// ── 2. Read current firmware version ───────────────────────────────────
old_version = http_get(
    url     = "http://<device-ip>/api/DeviceIdent",
    headers = { "Authorization": basic_auth("Service", "<password>") }
).json["data"]["Version"]

// ── 3. Upload firmware package ─────────────────────────────────────────
firmware_bytes = read_file("firmware.spk.signed")
http_put(
    url     = "http://<device-ip>/api/update",
    headers = {
        "Authorization":   basic_auth("Service", "<password>"),
        "X-Session-Token": token,
        "Content-Type":    "application/octet-stream"
    },
    body    = firmware_bytes
)

// ── 4. Trigger ─────────────────────────────────────────────────────────
for i in range(6):                                // poll up to 30 s
    sleep(5000 ms)
    state = get_update_state()                    // GET /api/UpdateState
    if state != 0:
        break                                     // auto-started
else:
    http_post("/api/methods/RunFirmwareUpdate")   // explicit trigger

// ── 5. Poll until finished or device reboots ───────────────────────────
deadline = now() + 300 s
while now() < deadline:
    sleep(5000 ms)
    try:
        state = get_update_state()
        if state == 2:                            // Finished
            break
        if state == 3:                            // Error
            raise Error("Update failed")
    except NetworkError:
        break                                     // device is rebooting

// ── 6. Wait for device to come back online ─────────────────────────────
reconnect_deadline = now() + 60 s
while now() < reconnect_deadline:
    sleep(5000 ms)
    try:
        new_version = http_get("/api/DeviceIdent").json["data"]["Version"]
        print("Update successful:", old_version, "->", new_version)
        break
    except NetworkError:
        continue                                  // still rebooting
Keywords:
firmware update, OTA, REST API, PUT /api/update, RunFirmwareUpdate, UpdateState, secure boot, signed firmware, .spk, flash, DeviceIdent, remote update, firmware upgrade
Create request