Elias Groot
Software Lead, Project Administrator
Bootspec
Bootspec is the term used for the JSON string in the environment variable ASE_SERVICE that is injected into a service's runtime by roverd. It serves as the address book
that any service can use to determine the service identity, socket addresses and configuration values.
Intuition: the bootspec JSON environment variable is generated by processing all service.yaml files in a pipeline.
Bootspec Layout
The following bootspec JSON is generated by roverd after validation of the example service.yaml and injected into the service runtime shell:
{
"name": "controller", // the name is replaced by the alias in the "as" field
"author": "vu-ase",
"version": "1.0.0",
"inputs": [{
"service": "imaging",
"streams": [{
"name": "track",
"address": "tcp://localhost:7890" // protocol "TCP" and port 7890 are chosen by roverd
},
{
"name": "debug",
"address": "tcp://localhost:7891" // protocol "TCP" and port 7891 are chosen by roverd
}
]
},
{
"service": "controller",
"streams": [{
"name": "decision",
"address": "tcp://localhost:7892" // protocol "TCP" and port 7892 are chosen by roverd
},
]
},
],
"outputs": [{
"name": "trajectory",
"address": "tcp://*:7893" // protocol "TCP" and port 7893 are chosen by roverd
}
],
"configuration": [{
"name": "speed",
"type": "number",
"tunable": false,
"value": 100
},
{
"name": "ki",
"type": "number",
"tunable": true,
"value": 123.0
},
{
"name": "kp",
"type": "string",
"tunable": true,
"value": "456"
}
],
"tuning": {
"enabled": true, // is set to true if there exists a service called "transceiver" in this pipeline
"address": "tcp://*:8829" // protocol "TCP" and port 8829 are chosen by roverd
}
}
A different example is also available here. Contents of a bootspec JSON string are validated according to the formal specification JSON schema that can be found here. This schema is used by a roverlib to generate parsing and validation code.
Service identity
The information about the service itself (taken from the service.yaml file) is injected through the bootspec environment variable. Consider the following service.yaml example:
...
name: example-service
author: vu-ase
version: 1.0.0
as: controller
...
Which will be injected through the bootspec by roverd as follows:
...
"name": "controller",
"author": "vu-ase",
"version": "1.0.0",
...
Notice that the name field in a service.yaml is replaced by its as field (if specified). The original name field will not be injected through the bootspec if an as alias is specified.
Commands
The commands section of a service.yaml file (commands.build and commands.run) are not injected through a bootspec.
Inputs
A service can depend on inputs, which describe communication streams to read from. The inputs are specified as service names in a service.yaml file. For example:
...
inputs:
- service: imaging
streams:
- track
- debug
- service: controller
streams:
- decision
...
roverd will validate the pipeline and try to match all inputs with the available outputs. It allocates protocols and ports for communication over streams. The example code above could get the following bootspec injected:
...
"inputs": [{
"service": "imaging",
"streams": [{
"name": "track",
"address": "tcp://localhost:7890" // protocol "TCP" and port 7890 are chosen by roverd
},
{
"name": "debug",
"address": "tcp://localhost:7891" // protocol "TCP" and port 7891 are chosen by roverd
}
]
},
{
"service": "controller",
"streams": [{
"name": "decision",
"address": "tcp://localhost:7892" // protocol "TCP" and port 7892 are chosen by roverd
},
]
},
],
...
The address information can be used by a service to set up a stream. This is already done for services that use a roverlib.
Outputs
Similar to inputs, outputs defined in a service.yaml are given an address and protocol by roverd. Consider the following outputs as defined in a service.yaml file:
...
outputs:
- trajectory
...
Which will be converted to the following section of the bootspec:
...
"outputs": [{
"name": "trajectory",
"address": "tcp://*:7893" // protocol "TCP" and port 7893 are chosen by roverd
}
],
...
Configuration Values
For any service, runtime configuration values can be specified in the service.yaml. These values are then injected into the bootspec with full information retained. Consider the following service.yaml:
...
configuration:
- name: speed
value: 1.0
type: number
- name: ki
value: 123
type: number
tunable: true # do you want to be able to change this value during runtime?
- name: kp
value: 456
tunable: true
type: string
...
Which will be converted to the following section of the bootspec:
...
"configuration": [{
"name": "speed",
"type": "number",
"tunable": false,
"value": 100
},
{
"name": "ki",
"type": "number",
"tunable": true,
"value": 123.0
},
{
"name": "kp",
"type": "string",
"tunable": true,
"value": "456"
}
],
...
Tuning
To enable tuning a service, information on where to read tuning data from is provided in the tuning field of the bootspec. This information can be used to set up a stream, as is done by a roverlib. If tuning is disabled, no address is specified.
...
"tuning": {
"enabled": true,
"address": "tcp://*:8829" // protocol "TCP" and port 8829 are chosen by roverd
}
...