Skip to main content

Update desired state

PATCH 
/v2/devices/:id/state

Update desired state

Partially update the state of a telematics device by setting a desired state. Partially update means that only configurations in the update will be changed. Any configurations not set will be ignored and remain unchanged. Multiple configurations can be changed in one update.

Currently the configurations are the following and will be expanded over time:

  • CAN Profile configuration
  • Input filtering configuration
  • Set output mode
  • Setup Bluetooth advertising
  • Change input name
  • Setup Modbus profile
  • Setup Operating Mode
  • Setup WiFi

The states that are available for a given telematics device vary by device type, customer and firmware versions. See the Get desired state documentation endpoint to fetch the list of available states for a given telematics device.

Examples on how to update a desired state of a telematics device​

Configure the CAN Profile to “Profile 1” with id 123:

{
    "desired": {
        "canbus": {
            "profile": {
                "id": 123
            }
        }
    }
}

Configure both the CAN Profile and inputFiltering in one update:

{
    "desired": {
        "canbus": {
            "profile": {
                "name": "Test profile",
                "id": 456
            }
        },
        "io": {
            "inputFiltering": {
                "enabled": "true"
            }
        }
    }
}

Configure WiFi for TU700

Note: there are different security types

AUTOMATIC, OPEN, WPA_PSK, WPA2_PSK, WPA3_PSK

{
    "desired": {
        "wifi": {
            "profiles": [
                {
                    "ssid": "MySSID1",
                    "securityType": "WPA2_PSK",
                    "password": "my_password1"
                },
                {
                    "ssid": "MySSID2",
                    "securityType": "AUTOMATIC",
                    "password": "my_password2"
                }
            ]
        }
    }
}

Configure Bluetooth advertising

{
    "desired": {
        "bluetooth": {
            "advertising": {
                "name": "My BLE device",
                "enabled": "true"
            }
        }
    }
}

Use the Get device state to follow up on the execution.

Configure both Operating Mode and adding input name in one update:

{
    "desired": {
        "operatingMode": {
            "mode": "normal"
        },
        "io": {
            "input2": {
                "name": "Ignition"
            }
        }
    }
}

Configure Operating Mode and Variant at the same time (paid addon):

{
    “desired”: {
        “operatingMode”: {
            “mode”: “normal”,
            “variant”: {
                “id”: “1111111-1111-1111-1111-111111111111"
            }
        }
    }
}

Validation errors​

The endpoint validates the request body against a JSON schema before processing. When validation fails the endpoint returns HTTP 400 Bad Request with an error response describing what went wrong. Below are examples of common validation errors grouped by category.

The error response format is:

{
    "status": 400,
    "message": "<validation error details>"
}

Boundary / range errors​

WiFi password too short — the password must be between 8 and 63 characters:

Request:

{
    "desired": {
        "wifi": {
            "profiles": [
                {
                    "ssid": "MyNetwork",
                    "password": "short",
                    "securityType": "WPA2_PSK"
                }
            ]
        }
    }
}

Error response:

{
    "status": 400,
    "message": "[$.properties.wifi.properties.profiles.items.$ref.properties.password.minLength]: $.wifi.profiles[0].password: must be at least 8 characters long"
}

WiFi channel out of range — the channel value must be between 0 and 177:

Request:

{
    "desired": {
        "wifi": {
            "profiles": [
                {
                    "ssid": "MyNetwork",
                    "password": "my_secure_password",
                    "securityType": "WPA2_PSK",
                    "channel": 200
                }
            ]
        }
    }
}

Error response:

{
    "status": 400,
    "message": "[$.properties.wifi.properties.profiles.items.$ref.properties.channel.maximum]: $.wifi.profiles[0].channel: must have a maximum value of 177"
}

Unknown enum value errors​

Unknown WiFi security type — allowed values are AUTOMATIC, WPA_PSK, WPA2_PSK, WPA3_PSK, and OPEN:

Request:

{
    "desired": {
        "wifi": {
            "profiles": [
                {
                    "ssid": "MyNetwork",
                    "password": "my_secure_password",
                    "securityType": "WEP"
                }
            ]
        }
    }
}

Error response:

{
    "status": 400,
    "message": "[$.properties.wifi.properties.profiles.items.$ref.properties.securityType.enum]: $.wifi.profiles[0].securityType: does not have a value in the enumeration [\"AUTOMATIC\", \"WPA_PSK\", \"WPA2_PSK\", \"WPA3_PSK\", \"OPEN\"]"
}

Unknown Operating Mode — allowed values are normal, restricted, stock, transport, batteryguard, and highavailability:

Request:

{
    "desired": {
        "operatingMode": {
            "mode": "sleep"
        }
    }
}

Error response:

{
    "status": 400,
    "message": "[$.properties.operatingMode.properties.mode.enum]: $.operatingMode.mode: does not have a value in the enumeration [\"normal\", \"restricted\", \"stock\", \"transport\", \"batteryguard\", \"highavailability\"]"
}

Structural errors​

Unknown / unexpected property — only properties defined in the schema are accepted:

Request:

{
    "desired": {
        "unknownProperty": {
            "value": 42
        }
    }
}

Error response:

{
    "status": 400,
    "message": "[$.additionalProperties]: $: property 'unknownProperty' is not defined in the schema and the schema does not allow additional properties"
}

Missing required field — a WiFi profile requires ssid, password and securityType (unless the _delete flag is set):

Request:

{
    "desired": {
        "wifi": {
            "profiles": [
                {
                    "ssid": "MyNetwork",
                    "password": "my_secure_password"
                }
            ]
        }
    }
}

Error response:

{
    "status": 400,
    "message": "[$.properties.wifi.properties.profiles.items.$ref.else.required]: $.wifi.profiles[0]: required property 'securityType' not found"
}

Array size exceeded — a maximum of 10 WiFi profiles can be configured:

Request:

{
    "desired": {
        "wifi": {
            "profiles": [
                { "ssid": "Network1", "password": "password_01", "securityType": "WPA2_PSK" },
                { "ssid": "Network2", "password": "password_02", "securityType": "WPA2_PSK" },
                { "ssid": "Network3", "password": "password_03", "securityType": "WPA2_PSK" },
                { "ssid": "Network4", "password": "password_04", "securityType": "WPA2_PSK" },
                { "ssid": "Network5", "password": "password_05", "securityType": "WPA2_PSK" },
                { "ssid": "Network6", "password": "password_06", "securityType": "WPA2_PSK" },
                { "ssid": "Network7", "password": "password_07", "securityType": "WPA2_PSK" },
                { "ssid": "Network8", "password": "password_08", "securityType": "WPA2_PSK" },
                { "ssid": "Network9", "password": "password_09", "securityType": "WPA2_PSK" },
                { "ssid": "Network10", "password": "password_10", "securityType": "WPA2_PSK" },
                { "ssid": "Network11", "password": "password_11", "securityType": "WPA2_PSK" }
            ]
        }
    }
}

Error response:

{
    "status": 400,
    "message": "[$.properties.wifi.properties.profiles.maxItems]: $.wifi.profiles: must have at most 10 items but found 11"
}

Request​

Responses​

Partially update the desired state of a device