This section defines the “system” module (fdo_sys) specification which provides basic onboarding services for FDO capable devices. A module is a set of key-value pairs; they define the onboarding operations that can be performed on a given FDO device. Module key-value pairs are exchanged between the device and it’s owning Device Management Service. It is up to the owning management service and the device to interpret the key-value pairs in accordance with the module specification.

fdo_sys Module Definition

The system module defines basic onboarding operations such as downloading content and executing commands. The following table describes key-value pairs for the system module.

Key Name Value Meaning
fdo_sys:active CBOR Bool True to activate the fdo_sys module.
fdo_sys:exec CBOR Array of String values The command is put as array elements. The command performs a system call.
fdo_sys:filedesc CBOR String Describes a path to a file that will be used in subsequent file operations.
fdo_sys:write CBOR BSTR Appends a block of data to the current file description.

fdo_sys:exec Message

The fdo_sys:exec command performs a system call on the device. The value of this command is a CBOR Array of String values. The first string in the array is the command to execute and the remaining strings are the arguments to the command. It is expected that it would use “exec” (system call) or similar API to execute the command on the device.

JSON* (readable description) ["/bin/sh","startup.sh"]
CBOR 82 # array(2)
67 # text(7)
2F62696E2F7368 # "/bin/sh"
6A # text(10)
737461727475702E7368 # "startup.sh"
C example execvp(“/bin/sh”,(char* []) {“shartup.sh”})

fdo_sys:filedesc Message

The fdo_sys:filedesc message describes the path to a file the will be used as a part of the onboarding process. A zero-length file is expected to exist on the local file system after this command is received. If the described file already exists, it is truncated to zero length, otherwise a zero-length file is created. The permissions for the created file is set to read/write for the user account the module is running under. File permissions can subsequently be modified with the fdo_sys:exec command if needed. If a path is not included as a part of the file name, the file is created under current working directory of the module. All subsequent fdo_sys:write operations will append to this file. If another fdo_sys:filedesc message is received, all subsequent fdo_sys:write messages will start appending to the file specified by the fdo_sys:filedesc message.

fdo_sys:write Message

The fdo_sys:write message provides an array of bytes that gets appended to the file described by the last fdo_sys:filedesc message. If this message is sent without being preceded by fdo_sys:filedesc, then a message 255: INVALID_MESSAGE_ERROR will be thrown and TO2 will not be completed. Once a fdo_sys:filedesc message has been received, many fdo_sys:write messages can follow.

Examples

Below are examples of the fdo_sys messages encoded as CBOR. The JSON examples are just human readable definitions while the actual messages are always CBOR. The encoding includes the entire TO2.OwnerServiceInfo message include the isMore and isDone flags.

Device should advertise it supports fdo_sys.

NOTE: This example just includes the module list key value pairs and not all the required values for the devmod.

DeviceServiceInfo (devmod)

Diagnostic Notation (not used by protocol) [false, [[["devmod:active", "true"], ["devmod:nummodules", 1], ["devmod:modules", [1, 1, "fdo_sys"]]]]]
CBOR 82 # array(2)
F4 # primitive(20) - IsMoreSeviceInfo
81 # array(1) - ServiceInfo
83 # array(3) - ServiceInfo Key-Value Array
82 # array(2) - ServiceInfo Key-Value Pair 1
6D # text(13)
6465766D6F643A616374697665 # "devmod:active"
64 # text(4)
74727565 # "true"
82 # array(2) - ServiceInfo Key-Value Pair 2
71 # text(17)
6465766D6F643A6E756D6D6F64756C6573 # "devmod:nummodules"
01 # unsigned(1)
82 # array(2) - ServiceInfo Key-Value Pair 3
6E # text(14)
6465766D6F643A6D6F64756C6573 # "devmod:modules"
83 # array(3)
01 # unsigned(1) - Module Index
01 # unsigned(1) - Number of modules
67 # text(7)
66646F5F737973 # "fdo_sys"

OwnerServiceInfo

fdo_sys:active

Diagnostic Notation (not used by protocol) [true, false, [[["fdo_sys:active", true]]]]
CBOR 83 # array(3)
F5 # primitive(21) - IsMoreSeviceInfo
F4 # primitive(20) - IsDone
81 # array(1) - ServiceInfo
81 # array(1) - ServiceInfo Key-Value Array
82 # array(2) - ServiceInfo Key-Value Pair
6E # text(14)
66646F5F7379733A616374697665 # "fdo_sys:active"
F5 # primitive(21)

fdo_sys:filedesc

Diagnostic Notation (not used by protocol) [true, false, [[["fdo_sys:filedesc", "startup.bat"]]]]
CBOR 83 # array(3)
F5 # primitive(21) - IsMoreSeviceInfo
F4 # primitive(20) - IsDone
81 # array(1) - ServiceInfo
81 # array(1) - ServiceInfo Key-Value Array
82 # array(2) - ServiceInfo Key-Value Pair
70 # text(16)
66646F5F7379733A66696C6564657363 # "fdo_sys:filedesc"
6B # text(11)
737461727475702E626174 # "startup.bat"

fdo_sys:write

Diagnostic Notation (not used by protocol) [true, false, [[["fdo_sys:write", h'4045…']]]]
CBOR 83 # array(3)
F5 # primitive(21) - IsMoreSeviceInfo
F4 # primitive(20) - IsDone
81 # array(1) - ServiceInfo
81 # array(1) - ServiceInfo Key-Value Array
82 # array(2) - ServiceInfo Key-Value Pair
6D # text(13)
66646F5F7379733A7772697465 # "fdo_sys:write"
59 0116 # bytes(278)
4045.. # "@E" -rest of 278 byte file

fdo_sys:exec

Diagnostic Notation (not used by protocol) [false, true, [[["fdo_sys:exec", ["cmd", "/c", "startup.bat"]]]]
CBOR 83 # array(3)
F4 # primitive(20) - IsMoreSeviceInfo
F5 # primitive(21) - IsDone
81 # array(1) - ServiceInfo
81 # array(1) - ServiceInfo Key-Value Array
82 # array(2) - ServiceInfo Key-Value Pair
6C # text(12)
66646F5F7379733A65786563 # "fdo_sys:exec"
83 # array(3)
63 # text(3)
636D64 # "cmd"
62 # text(2)
2F63 # "/c"
6B # text(11)
737461727475702E626174 # "startup.bat"

ismore Flag

The 'ismore' more should be true is if the message being sent is not a complete processable message. All fdo_sys messages are complete messages, so the 'ismore' flag will always be true in this case.