Write a configuration in the device

Role

Write all the configuration registers into a device, then restart it to apply the new configuration.

Prototype

URL : /device/{$id}/config[?specific={$specific}]

Method : PUT

URL Params :

  • {$id} : the DeviceId of the device. Use GET /devices to enumerate the connected devices.
  • {$specific} : how to handle the device-specific registers. Possible values are discard (don't care for current values, write all the registers including the device-specific ones) and preserve (keep the current value of device-specific registers if they are already defined, ignore the corresponding data entries). Default is discard.

Request data : either an Address=Value list, or a CONFIG-DATA object.

Request data as an Address=Value list

Request data shall be a JSON associative array. Every entry is a Address-Value pair in the form

"Address of register (hexadecimal)" : "Value of register (hexadecimal)".

Since register addresses are on 2 bytes, the Address field is a 4-character hexadecimal string. The Value field is either an empty string ("") to store a blank value, or an hexadecimal string. The actual length must match the size of the register.

Valid values for register addresses are from 0200 to 03FF and therefore cover the Configuration bank and the Templates bank only.

Data structure

{
	"Address": "Value",
    ...
}

Example

{
	"0201": "44656D6F2062656E63682C20522644204C6162",    
	"02C0": "02",
	"0310": "12345678",
	"0311": "AB",
	"0327": "00CAFE01FECA02",
	"034C": "48656C6C6F2C20776F726C64"
}

NOTE:

All the Configuration and Templates registers that are not explicitly defined are cleared to their default value, exactly as if they were assigned a null value. There is no way to keep earlier values when writing a new configuration (except for the device-specific values that are kept if specific=preserve is set in the parameters of the request).

Request data as a CONFIG-DATA object

A CONFIG-DATA object may store more than the 0200 to 03FF registers allowed by the simple Address=Value format.

In particular, this object must be used to write security keys or to change the key settings in the device's Secure Elements, or to write X509 certificates in the device's Certificate Store.

When this methode is used, the Address field is one 1 byte only, therefore a 2-character hexadecimal string. The Value field is either an empty string ("") to store a blank value, or an hexadecimal string. The actual length must match the size of the register, key entry or certificate entry that is targetted.

It is also possible to change the understanding of the Value field by adding a Format modifier in the Address fields; see CONFIG-DATA Format modifier for details.

Data structure

{
    "config": {
        "Address": "Value,"
        ...
    },
    "templates": {
        "Address": "Value,"
        ...        
    },
    "samav": {
        "Address": "Value,"
        ...        
    },
    "atecc": {
        "Address": "Value,"
        ...        
    },
    "certificates": {
        "Address": "Value,"
        ...    
	}
}

Example

{
    "config": {
	"01.string": "Demo bench, R&D Lab",
	"C0": "02"
    },
    "templates": {
	"10": "12345678",
	"11": "AB",
	"27": "00CAFE01FECA02",
	"4C": "48656C6C6F2C20776F726C64"
    },
    "certificates": {
	"0E.base64": "MIID2DCCAsCgAwIBAgIJA (...) 0c6p0I2XkO+oQc0i5oAd229yLg"
    }
}

NOTES:

  • All the Configuration and Templates registers that are not explicitly defined are cleared to their default value, exactly as if they were assigned a null value. There is no way to keep earlier values when writing a new configuration (except for the device-specific values that are kept if specific=preserve is set in the parameters of the request).

  • On the other-hand, X509 certificates in the Certificate Store and security key in the Secure Elements that are not explicitely set in the CONFIG-DATA object are preserved. Write an empty value for any entry that should be cleared.

Success Response

Code : 200 OK

Content : a CONFIG-GUID object, as specified below.

CONFIG-GUID object definition

Field name Type Status Description
"Result" string always Constant value: "success"
"ConfigId" string always The new configuration GUID of the device

Example

{
	"Result": "success",
	"ConfigId": "80B4667D-71D0-0BDC-AA81-95DCA20A44E1"
}

Error Response

See Error Responses.