FPP JSON Dictionary Specification
This document describes the format of FPP JSON dictionaries.
Contents
- Type Descriptors
- Type Definitions
- Values
- Commands, Telemetry Channels, Events, and Parameters
- Data Products
- Telemetry Packet Sets
- Telemetry Packets
- Telemetry Packet Sets
- Dictionaries
Type Descriptors
A Type Descriptor is a JSON Dictionary that describes a type.
Primitive Integer Type Descriptors
Field | Description | Options | Required |
---|---|---|---|
name |
String representing the FPP type name | U8 , U16 , U32 , U64 , I8 , I16 , I32 , I64 |
true |
kind |
String representing the kind of type | integer |
true |
size |
Number of bits supported by the data type | 8 , 16 , 32 , 64 |
true |
signed |
Boolean indicating whether the integer is signed or unsigned | Boolean | true |
Unsigned Integer Types
- U8
- U16
- U32
- U64
Example: Type Descriptor for U64
Signed Integer Types
- I8
- I16
- I32
- I64
Example: Type Descriptor for I8
Floating-Point Type Descriptors
Field | Description | Options | Required |
---|---|---|---|
name |
String representing the FPP type name | F32 , F64 |
true |
kind |
String representing the kind of type | float |
true |
size |
Number of bits supported by the data type | 32 , 64 |
true |
Floating-Point Types
- F32
- F64
Example: Type Descriptor for F64
Boolean Type Descriptors
Field | Description | Options | Required |
---|---|---|---|
name |
String representing the FPP type name | bool |
true |
kind |
String representing the kind of type | bool |
true |
size |
Number of bits supported by the data type | 8 |
true |
Boolean Types
- true
- false
Example: Type Descriptor for booleans
String Type Descriptors
Field | Description | Options | Required |
---|---|---|---|
name |
String representing the FPP type name | string |
true |
kind |
String representing the kind of type | string |
true |
size |
Number representing the maximum string size in bytes | Number in the range [1, 231) | true |
String Types
Any sequence of characters
Example Type Descriptor for string
Qualified Identifier Type Descriptors
A Qualified Identifier is a kind of Type Descriptor that refers to a Type Definition.
Field | Description | Options | Required |
---|---|---|---|
name |
String representing the fully qualified FPP type name | Period-separated String | true |
kind |
String representing the kind of type | qualifiedIdentifier | true |
Example JSON of qualified name
Type Definitions
Array Type Definition
Field | Description | Options | Required |
---|---|---|---|
kind |
The kind of type | array |
true |
qualifiedName |
Fully qualified name of element in FPP model | Period-separated String | true |
size |
Size of the data structure | Number | true |
elementType |
The type of the array's elements | Type Descriptor | true |
default |
Default array value | Value of type specified in elementType |
true |
annotation |
User-defined annotation | String | false |
Example FPP model with JSON representation:
{
"kind": "array",
"qualifiedName": "M1.A",
"size": 3,
"elementType": {
"name": "U8",
"kind": "integer",
"signed": false,
"size": 8
},
"default": [0, 0, 0],
"annotation": "My array named A"
}
Enumeration Type Definition
Field | Description | Options | Required |
---|---|---|---|
kind |
The kind of type | enum |
true |
qualifiedName |
Fully qualified name of element in FPP model | Period-separated String | true |
representationType |
Type of the enumerated values | Type Descriptor | true |
enumeratedConstants |
The enumerated constants | JSON Dictionary of enumerated constants (keys) to Enumerated Constant Descriptor (values) | true |
default |
Qualified name of the enumeration's default value | String | true |
annotation |
User-defined annotation | String | false |
Enumerated Constant Descriptors
Field | Description | Options | Required |
---|---|---|---|
name |
Name of the enumerated constant | String | true |
value |
Value associated to the enumerated constant | Number | true |
annotation |
User-defined annotation for the enumerated constant | String | false |
Example FPP model with JSON representation:
module M1 {
@ Schroedinger's status
enum Status {
YES
NO
MAYBE @< The cat would know
} default MAYBE
}
{
"kind": "enum",
"qualifiedName": "M1.Status",
"representationType": {
"name": "I32",
"kind": "integer",
"signed": true,
"size": 32
},
"enumeratedConstants": [
{
"name": "YES",
"value" : 0
},
{
"name": "NO",
"value" : 1
},
{
"name" : "MAYBE",
"value" : 2,
"annotation": "The cat would know"
},
],
"default": "M.Status.MAYBE",
"annotation": "Schroedinger's status"
}
Struct Type Definition
Struct Type Definition
Field | Description | Options | Required |
---|---|---|---|
kind |
The kind of type | struct |
true |
qualifiedName |
Fully qualified name of element in FPP model | Period-separated String | true |
members |
The members of the struct | JSON dictionary of Member Name (key) to Struct Member Descriptor (value) | true |
default |
The default value of the struct | JSON dictionary of Member Name (key) to default value (value) | true |
annotation |
User-defined annotation | String extracted from FPP model | false |
Struct Member Descriptor
Field | Description | Options | Required |
---|---|---|---|
type |
Type Descriptor of member | Type Descriptor | true |
index |
Index of the struct member | Number | true |
size |
Size of the struct member | Number | false |
format |
Format specifier | String | false |
annotation |
User-defined annotation | String extracted from FPP model | false |
Example FPP model with JSON representation:
{
"kind": "struct",
"qualifiedName": "M1.S",
"annotation": "Struct for wxy values",
"members": {
"w": {
"type": {
"name": "M.S.w",
"kind": "qualifiedIdentifier"
},
"index": 0,
"size": 3,
"annotation" : "This is an array"
},
"x": {
"type": {
"name": "U32",
"kind": "integer",
"signed": false,
"size": 32
},
"format": "the count is {}",
"index": 1
},
"y": {
"type": {
"name": "F32",
"kind": "float",
"size": 32
},
"index": 2
}
},
"default": {
"w": [0, 0, 0],
"x": 0,
"y": 0
},
}
Type Alias Definition
Field | Description | Options | Required |
---|---|---|---|
kind |
The kind of type | alias |
true |
qualifiedName |
Fully qualified name of element in FPP model | Period-separated String | true |
type |
Type Descriptor of the alias | Type Descriptor | true |
underlyingType |
Type Descriptor of the underlying type of the alias | Type Descriptor | true |
annotation |
User-defined annotation | String extracted from FPP model | false |
Example FPP model with JSON representation:
[
{
"kind": "alias",
"qualifiedName": "M1.A1",
"type": {
"name": "U32",
"kind": "integer",
"signed": false,
"size": 32
},
"underlyingType": {
"name": "U32",
"kind": "integer",
"signed": false,
"size": 32
},
"annotation": "Alias of type U32"
},
{
"kind": "alias",
"qualifiedName": "M1.A2",
"type": {
"name": "M1.A1",
"kind": "qualifiedIdentifier"
},
"underlyingType": {
"name": "U32",
"kind": "integer",
"signed": false,
"size": 32
},
"annotation": "Alias of type A2"
}
]
Values
Primitive Integer Values
Number representing integer value
Example JSON of type U8 with a value of 2:
Example JSON of type I8 with a value of -2:
Floating-Point Values
Number representing float value
Example JSON of type F32 with a value of 10.0
Boolean Values
Boolean value
Example JSON of type bool with a value of true
String Values
String containing sequence of characters
Example JSON of type string with a value of "Hello World!"
Array Values
Array with elements
Example JSON of an array of type U32 consisting of 10 elements
Enumeration Values
String qualified identifier name of enumeration value
Example JSON of an enum
Struct Values
JSON Dictionary consisting of String qualified identifier names (keys) and values (values)
Example JSON of a struct:
Invalid Values
Null Values
Field | Description | Options | Required |
---|---|---|---|
name |
String indicating that the value is null | null | true |
kind |
String indicating that the kind of value is invalid | invalid | true |
Infinity Values
Field | Description | Options | Required |
---|---|---|---|
name |
String indicating that the value is infinity | infinity | true |
kind |
String indicating that the kind of value is invalid | invalid | true |
Negative Infinity Values
Field | Description | Options | Required |
---|---|---|---|
name |
String indicating that the value is negative infinity | negativeInfinity | true |
kind |
String indicating that the kind of value is invalid | invalid | true |
Commands, Telemetry Channels, Events, and Parameters
Formal Parameters
Formal Parameters are used in Commands and Events definitions.
Field | Description | Options | Required |
---|---|---|---|
name |
Name of parameter | String | true |
type |
Type Descriptor of parameter | Type Descriptor | true |
ref |
Boolean indicating whether the formal parameter is to be passed by referenced when it is used in a synchronous port invocation | Boolean | true |
annotation |
User-defined annotation of parameter | String | false |
{
"name": "param1",
"type": {
"name": "U32",
"kind": "integer",
"size": 32,
"signed": false,
},
"ref": false,
"annotation": "This is param1"
}
Commands
Field | Description | Options | Required |
---|---|---|---|
name |
Fully qualified name of the command | Period-separated String | true |
commandKind |
The kind of command | async , guarded , sync , set , save |
true |
opcode |
Command opcode | Number | true |
formalParams |
Parameters of the command | Array of Formal Parameters | true |
annotation |
User-defined annotation of command | String | false |
priority |
Priority for the command on the input queue | Number | required for async command kinds |
queueFullBehavior |
Behavior of the command when the input full is queue | assert , block , drop |
required for async command kinds |
Example Command in FPP:
module M {
active component Component1 {
@ A sync command with parameters
sync command SyncParams(
param1: U32 @< Param 1
param2: string @< Param 2
) opcode 0x01
}
instance c1: Component1 base id 0x100 \
queue size 10
topology T {
instance c1
}
}
{
"name": "M.c1.SyncParams",
"commandKind": "sync",
"opcode": 257,
"annotation": "A sync command with parameters",
"formalParams": [
{
"name": "param1",
"annotation": "Param 1",
"type": {
"name": "U32",
"kind": "integer",
"size": 32,
"signed": false,
},
"ref": false
},
{
"name": "param2",
"annotation": "Param 2",
"type": {
"name": "string",
"kind": "string",
"size": "80"
},
"ref": false
}
],
}
Telemetry Channels
Field | Description | Options | Required |
---|---|---|---|
name |
Fully qualified name of the telemetry channel | Period-separated String | true |
type |
Type Descriptor of the telemetry channel | Type Descriptor | true |
id |
Numeric identifier of the channel | Number | true |
telemetryUpdate |
Update specifier of the telemetry channel | always , on change |
true |
format |
Format string of the channel | String | false |
annotation |
User-defined annotation of channel | String | false |
limit |
Low and high limits of the channel | JSON dictionary | false |
Example FPP model with JSON representation:
module M {
active component Component1 {
@ Telemetry channel 1
telemetry Channel1: F64 \
id 0x02 \
update on change \
low { yellow -1, orange -2, red -3 } \
high { yellow 1, orange 2, red 3 }
}
instance c1: Component1 base id 0x100 \
queue size 10
topology T {
instance c1
}
}
[
{
"name": "M.c1.Channel1",
"annotation": "Telemetry channel 1",
"type": {
"name": "F64",
"kind": "float",
"size": 64
},
"id": 258,
"telemetryUpdate": "on change",
"limit": {
"low": {
"yellow": -1,
"orange": -2,
"red": -3
},
"high": {
"yellow": 1,
"orange": 2,
"red": 3
}
}
}
]
Events
Field | Description | Options | Required |
---|---|---|---|
name |
Fully qualified name of the event | Period-separated String | true |
severity |
Severity of the event | ACTIVITY_HI , ACTIVITY_LO , COMMAND , DIAGNOSTIC , FATAL , WARNING_HI , WARNING_LO |
true |
formalParams |
Parameters of the event | Array of Formal Parameters | true |
id |
Numeric identifier of the event | Number | true |
format |
Format string of the event | String | true |
throttle |
Maximum number of times to emit the event before throttling it | Number | false |
annotation |
User-defined annotation of the event | String | false |
Example FPP model with JSON representation:
module M {
active component Component1 {
@ This is the annotation for Event 1
event Event1(
arg1: U32 @< Argument 1
) \
severity activity low \
id 0x03 \
format "Event 1 occurred"
}
instance c1: Component1 base id 0x100 \
queue size 10
topology T {
instance c1
}
}
{
"name": "M.c1.Event1",
"annotation": "This is the annotation for Event 1",
"severity": "ACTIVITY_LO",
"formalParams": [
{
"name": "arg1",
"annotation": "Argument 1",
"type": {
"name": "U32",
"kind": "integer",
"size": 32,
"signed": false,
},
"ref": false
}
],
"id": 259,
"format": "Event 1 occurred",
}
Parameters
Field | Description | Options | Required |
---|---|---|---|
name |
Fully qualified name of the parameter | Period-separated String | true |
type |
Type Descriptor of the parameter | Type Descriptor | true |
id |
Numeric identifier of the parameter | Number | true |
default |
Default value (of type specified in type ) of the parameter |
Value of type specified in type |
false |
annotation |
User-defined annotation of parameter | String | false |
Example FPP model with JSON representation:
module M {
active component Component1 {
@ This is the annotation for Parameter 1
param Parameter1: U32 \
id 0x04 \
}
instance c1: Component1 base id 0x100 \
queue size 10
topology T {
instance c1
}
}
{
"name": "M.c1.Parameter1",
"type": {
"name": "U32",
"kind": "integer",
"signed": false,
"size": 32
},
"id": "260",
"annotation": "This is the annotation for Parameter 1",
"default": 0
}
Data Products
Records
Field | Description | Options | Required |
---|---|---|---|
name |
Fully qualified name of the record | Period-separated String | true |
type |
Type Descriptor the record | Type Descriptor | true |
array |
Boolean specifying whether the record stores a variable number of elements | Boolean | true |
id |
The numeric identifier of the record | Number | true |
annotation |
User-defined annotation of record | String | false |
Example FPP model with JSON representation:
module M {
active component Component1 {
@ Record 0: A variable number of F32 values
product record Record0: F32 array id 0x05
@ Record 1: A single U32 value
product record Record1: U32 id 0x06
}
instance c1: Component1 base id 0x100 \
queue size 10
topology T {
instance c1
}
}
[
{
"name": "M.c1.Record0",
"annotation": "Record 0: A variable number of F32 values",
"type": {
"name": "F32",
"kind": "float",
"size": 32
},
"array": true,
"id": 261
},
{
"name": "M.c1.Record1",
"annotation": "Record 1: A single U32 value",
"type": {
"name": "U32",
"kind": "integer",
"signed": false,
"size": 32
},
"array": false,
"id": 262
}
]
Containers
Field | Description | Options | Required |
---|---|---|---|
name |
Fully qualified name of the container | Period-separated String | true |
id |
The numeric identifier of the record | Number | true |
defaultPriority |
The downlink priority for the container | Number | false |
annotation |
User-defined annotation of container | String | false |
Example FPP model with JSON representation:
module M {
active component Component1 {
@ Container 0
product container Container0 id 0x07
@ Container 1
product container Container1 id 0x08
@ Container 2
product container Container2 id 0x09 default priority 10
}
instance c1: Component1 base id 0x100 \
queue size 10
topology T {
instance c1
}
}
[
{
"name": "M.c1.Container0",
"annotation": "Container 0",
"id": 263,
},
{
"name": "M.c1.Container1",
"annotation": "Container 1",
"id": 264,
},
{
"name": "M.c1.Container2",
"annotation": "Container 2",
"id": 265,
"defaultPriority": 259
}
]
Telemetry Packet Sets
Telemetry Packets
Field | Description | Options | Required |
---|---|---|---|
name |
Name of the telemetry packet | String | true |
id |
Numeric identifier of the packet | Number | true |
group |
Packet group number | Number | true |
members |
Telemetry Channels in the packet | Array of Fully Qualified Names of Telemetry Channels | true |
Telemetry Packet Sets
Field | Description | Options | Required |
---|---|---|---|
name |
Name of the telemetry packet set | String | true |
members |
Telemetry Packets in the set | Array of Telemetry Packets | true |
omitted |
Telemetry Channels omitted from the set | Array of Fully Qualified Names of Telemetry Channels | true |
Example FPP model with JSON representation:
module M {
active component Component1 {
@ Telemetry channel 0
telemetry Channel0: U32 id 0x00
@ Telemetry channel 1
telemetry Channel1: U32 \
id 0x01 \
update on change
@ Telemetry channel 2
telemetry Channel2: F64 \
id 0x02 \
format "{.3f}"
}
instance c1: Component1 base id 0x100 \
queue size 10
topology T {
instance c1
telemetry packets Packets {
packet P1 id 0 level 0 {
M.c1.Channel0
M.c1.Channel1
}
} omit {
M.c1.Channel2
}
}
}
[
{
"name" : "Packets",
"members" : [
{
"name" : "P1",
"id" : 0,
"group" : 0,
"members" : [
"M.c1.Channel0",
"M.c1.Channel1"
]
}
],
"omitted" : [
"M.c1.Channel2"
]
}
]
Dictionaries
Dictionary Metadata
Field | Description | Options | Required |
---|---|---|---|
deploymentName |
String representing the fully qualified name of the topology | String | true |
frameworkVersion |
String representing the F´ framework version (semantic versioning) | String | true |
projectVersion |
String representing the project version (semantic versioning) | String | true |
libraryVersions |
Array of Strings corresponding to the version (semantic versioning) of libraries used by the F´ project | Array of Strings | true |
dictionarySpecVersion |
String representing the JSON dictionary specification version | String | true |
Dictionary Content
Field | Content | Required |
---|---|---|
metadata |
Dictionary Metadata | true |
typeDefinitions |
Array of Type Definitions | true |
commands |
Array of Commands | true |
events |
Array of Events | true |
telemetryChannels |
Array of Telemetry Channels | true |
parameters |
Array of Parameters | true |
records |
Array of Records | true |
containers |
Array of Containers | true |
telemetryPacketSets |
Array of Telemetry Packet Sets | true |
Example FPP model with JSON representation:
module M {
array StringArray = [2] string size 80 default [ "A", "B"]
enum StatusEnum {
YES
NO
MAYBE
} default MAYBE
struct A {
x: U32 format "The value of x is {}"
y: F32 format "The value of y is {}"
} default { x = 1, y = 1.15}
active component Component1 {
@ A command with a single StringArray argument
sync command CommandString(
arg1: M.StringArray @< description for argument 1
) opcode 0x01
@ This is the annotation for Parameter 1
param Parameter1: A \
id 0x02 \
set opcode 0x03 \
save opcode 0x04
@ Event with one StatusEnum argument
event Event1(
arg1: M.StatusEnum @< Description of arg1 formal param
) \
severity activity high \
id 0x05 \
format "Event 1 occurred, status {}"
@ Telemetry channel 1 of type I32
telemetry Channel1: I32 \
id 0x06 \
update on change \
low { yellow -1, orange -2, red -3 } \
high { yellow 1, orange 2, red 3 }
@ Record 0: A variable number of F32 values
product record Record0: F32 array id 0x05
@ Record 1: A single U32 value
product record Record1: U32 id 0x06
@ Container 0
product container Container0 id 0x07
@ Container 1
product container Container1 id 0x08
@ Container 2
product container Container2 id 0x09 default priority 10
}
instance c1: Component1 base id 0x100 \
queue size 10
topology T {
instance c1
telemetry packets Packets {
packet P1 id 0 level 0 {
M.c1.Channel1
}
}
}
}
{
"metadata": {
"deploymentName": "M.T",
"frameworkVersion": "3.3.2",
"projectVersion": "1.0.0",
"libraryVersions": [],
"dictionarySpecVersion": "1.0.0"
},
"typeDefinitions" : [
{
"kind" : "array",
"qualifiedName" : "M.StringArray",
"size" : 2,
"elementType" : {
"name" : "string",
"kind" : "string",
"size" : 80
},
"default" : [
"A",
"B"
],
"annotation" : "An array of 2 String values"
},
{
"kind" : "enum",
"qualifiedName" : "M.StatusEnum",
"representationType" : {
"name" : "U8",
"kind" : "integer",
"size" : 8,
"signed" : false
},
"enumeratedConstants" : [
{
"name" : "YES",
"value" : 0
},
{
"name" : "NO",
"value" : 1
},
{
"name" : "MAYBE",
"value" : 2
}
],
"default" : "M1.StatusEnum.MAYBE"
},
{
"kind" : "struct",
"qualifiedName" : "M.A",
"members" : {
"x" : {
"type" : {
"name" : "U32",
"kind" : "integer",
"size" : 32,
"signed" : false
},
"index" : 0,
"format" : "The value of x is {}"
},
"y" : {
"type" : {
"name" : "F32",
"kind" : "float",
"size" : 32
},
"index" : 1,
"format" : "The value of y is {}"
}
},
"default" : {
"x" : 1,
"y" : 1.15
}
}
],
"commands" : [
{
"name" : "M.c1.CommandString",
"commandKind" : "sync",
"opcode" : 257,
"formalParams" : [
{
"name" : "arg1",
"type" : {
"name" : "M.StringArray",
"kind" : "qualifiedIdentifier"
},
"ref" : false,
"annotation" : "description for argument 1"
}
],
"annotation" : "A command with a single StringArray argument"
},
{
"name" : "M.c1.Parameter1_PRM_SET",
"commandKind" : "set",
"opcode" : 259,
"formalParams" : [
{
"name" : "val",
"type" : {
"name" : "M.A",
"kind" : "qualifiedIdentifier"
},
"ref" : false
}
],
"annotation" : "Parameter (struct)"
},
{
"name" : "M.c1.Parameter1_PRM_SAVE",
"commandKind" : "save",
"opcode" : 260,
"formalParams" : [
],
"annotation" : "Parameter (struct)"
}
],
"parameters" : [
{
"name" : "M.c1.Parameter1",
"type" : {
"name" : "M.A",
"kind" : "qualifiedIdentifier"
},
"id" : 258,
"default" : {
"x" : 1,
"y" : 1.15
},
"annotation" : "Parameter (struct)"
}
],
"events" : [
{
"name" : "M.c1.Event1",
"severity" : "ACTIVITY_HI",
"formalParams" : [
{
"name" : "arg1",
"type" : {
"name" : "M.StatusEnum",
"kind" : "qualifiedIdentifier"
},
"ref" : false,
"annotation" : "Description of arg1 formal param"
}
],
"id" : 259,
"format" : "Event 1 occurred, status {}",
"annotation" : "Event with one StatusEnum argument"
}
],
"telemetryChannels" : [
{
"name" : "M.c1.Channel1",
"type" : {
"name" : "I32",
"kind" : "integer",
"size" : 32
},
"id" : 260,
"telemetryUpdate" : "on change",
"annotation" : "Telemetry channel 1 of type I32",
"limit": {
"low": {
"yellow": "-1",
"orange": "-2",
"red": "-3"
},
"high": {
"yellow": "1",
"orange": "2",
"red": "3"
}
}
}
],
"records" : [
{
"name": "M.c1.Record0",
"annotation": "Record 0: A variable number of F32 values",
"type": {
"name": "F32",
"kind": "float",
"size": 32
},
"array": true,
"id": 261
},
{
"name": "M.c1.Record1",
"annotation": "Record 1: A single U32 value",
"type": {
"name": "U32",
"kind": "integer",
"signed": false,
"size": 32
},
"array": false,
"id": 262
}
],
"containers" : [
{
"name": "M.c1.Container0",
"annotation": "Container 0",
"id": 263,
},
{
"name": "M.c1.Container1",
"annotation": "Container 1",
"id": 264,
},
{
"name": "M.c1.Container2",
"annotation": "Container 2",
"id": 265,
"defaultPriority": 10
}
],
"telemetryPacketSets": [
{
"name" : "Packets",
"members" : [
{
"name" : "P1",
"id" : 0,
"group" : 0,
"members" : [
"M.c1.Channel1"
]
}
],
"omitted" : []
}
]
}