Command Dictionary Introduction¶
AIT provides support for YAML-based configuration of commands with enough detail to provide verification of information (E.g., units) and encoding/decoding. The commands are constrained by the ISS 1553B command word design (64 total words with 11 reserved).
# An example command for setting the operation
# mode of an instrument.
--- !Command
name: CORE_SET_OP_MODE
opcode: 0x0001
subsystem: CORE
desc: |
This command sets the operational mode.
arguments:
- !Argument
name: mode
desc: Mode
units: none
type: U8
bytes: 0
enum:
0: SAFE
1: IDLE
2: SCANNING
3: SCIENCE
All the valid parameters and attributes that you can have in your command dictionary configuration file is controlled by the command dictionary schema file. You can view the full schema file in the AIT Core repo at ait/core/data/cmd_schema.json. A snippet of a schema is below. You can see that it allows for quite of bit of control over the command dictionary including nested object verification, individual attribute type checks, and required fields.
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Command Dictionary Schema",
"description": "Command Dictionary Schema",
"type": "array",
"items": {
"required": ["command", "name", "opcode"],
"additionalProperties": false,
"properties": {
"command": {
"type": "string"
},
"name": {
"type": "string"
},
"opcode": {
"type": "integer"
},
"subsystem": {
"type": "string"
},
"title": {
"type": "string"
},
"desc": {
"type": "string"
},
"arguments": {
... Nested Argument and Fixed Field Schemas snipped
}
}
}
}
AIT also provides a command line utility for verifying that your command dictionary configuration is valid given that you have a defined schema file. If you pass the --cmd
or -c
flag to ait-yaml-validate
it will check this for you.
$ ait-yaml-validate --cmd
016-07-27T09:36:21.408 | INFO | Validation: SUCCESS: ...
AIT provides command encoding/decoding via ait.core.cmd.CmdDict
.
>>> cmddict = ait.core.cmd.getDefaultDict()
>>> type(cmddict)
<class 'ait.core.cmd.CmdDict'>
You can create and encode a command directly from the command dictionary.
>>> noop = cmddict.create('NO_OP')
>>> type(noop)
<class 'ait.core.cmd.Cmd'>
>>> noop
NO_OP
>>> bin_noop = noop.encode()
>>> bin_noop
bytearray(b'\x00\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00')
Given a binary blob, you can also decode into a command.
>>> decoded_cmd = cmddict.decode(bin_noop)
>>> type(decoded_cmd)
<class 'ait.core.cmd.Cmd'>
>>> decoded_cmd
NO_OP
!Command¶
The AIT command constructor is the parent construct for all AIT command definitions. It encapsulates optional arguments and contains metadata critical to the command.
- name:
- A string denoting the name of this command
- opcode:
- The number assigned to this opcode. This is usually given in hexadecimal.
- subsystem (optional):
- A string denoting the subsystem associated with this command.
- title (optional):
- A string denoting the title of this command
- desc (optional):
- A string for providing a description of the command.
- arguments (optional):
- A list of !Argument or !Fixed objects
!Argument¶
The argument constructor allows for a number of parameter to specify options for a command. By default an argument needs to include a name, data type, and byte information.
- name:
- A string denoting the name of this argument
- type:
- A string specifying the data type of the argument. You can see all the valid primitive types that will be accepted here by looking at
ait.core.dtype.PrimitiveTypes
. - bytes:
- Specifies which byte(s) in the command filled by this argument. This can be specified as a single integer or as a list of integers (in the case of a range of bytes).
- desc (optional):
- A string for providing a description of the argument.
- units (optional):
- A string denoting the argument’s units.
- range (optional):
- A list of 2 items specifying the range of acceptable values for the argument.
- enum (optional):
- A dict of key, value pairs listing the enumeration of valid values for the argument. The key matches with the value in the command. The value is a string describing what the value in the enumeration represents.
!Fixed¶
The fixed constructor allows you to define constant values in your command.
- type:
- A string specifying the data type of the argument. You can see all the valid primitive types that will be accepted here by looking at
ait.core.dtype.PrimitiveTypes
. - bytes:
- Specifies which byte(s) in the command filled by this constant. This can be specified as a single integer or as a list of integers (in the case of a range of bytes).
- name (optional):
- A string denoting the name of this constant.
- desc (optional):
- A string for providing a description of the constant.
- units (optional):
- A string denoting the constant’s units.
- value (optional):
- A number specifying the value for this constant.
Example Command Definition¶
Below is an example of what you might have defined for a command. It uses most of the options mentioned above.
--- !Command
name: EXAMPLE_RESET_SYSTEM
opcode: 0x1337
subsystem: ExampleSubSystem
title: Example Reset System
desc: |
Reset the processor and initiate boot process.
arguments:
- !Fixed
type: LSB_U16
bytes: [0, 1]
value: 0x3010
- !Argument
name: reset_type
desc: |
Reset type
PROM_REBOOT: Nominal reboot
DIAG_RAM_REBOOT: Diagnostic reboot
units: none
type: LSB_U16
bytes: [2, 3]
enum:
0x0000: PROM_REBOOT
0x0001: DIAG_RAM_REBOOT
- !Fixed
type: LSB_U16
bytes: [4, 5]
value: 0x0000
- !Fixed
type: LSB_U16
bytes: [6, 7]
value: 0x0000