FPP JSON Dictionary Specification

This document describes the format of FPP JSON dictionaries.

Contents

• Type Names
  • Primitive Integer Type Names
    • Unsigned Integer Types
    • Signed Integer Types
  • Floating-Point Type Names
    • Floating-Point Types
  • Boolean Type Name
    • Boolean Types
  • String Type Names
    • String Types
  • Qualified Identifier Type Names
• Type Definitions
  • Array Type Definition
  • Enumeration Type Definition
  • Struct Type Definition
    • Struct Member
    • Struct Type Definition
• Values
  • Primitive Integer Values
  • Floating-Point Values
  • Boolean Values
  • String Values
  • Array Values
  • Enumeration Values
  • Struct Values
  • Invalid Values
    • Null Values
    • Infinity Values
    • Negative Infinity Values
• Parameters, Commands, Telemetry Channels, and Events
  • Formal Parameters
  • Parameters
  • Commands
  • Telemetry Channels
  • Events
• Data Products
  • Record
  • Container
• Dictionaries
  • Dictionary Metadata
  • Dictionary Content

Type Names

Primitive Integer Type Names

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 JSON of U8

{
    "name": "U8",
    "kind": "integer",
    "size": 8,
    "signed": false,
}

Example JSON of U64

{
    "name": "U64",
    "kind": "integer",
    "size": 64,
    "signed": false,
}

Signed Integer Types

• I8
• I16
• I32
• I64

Example JSON of I8

{
    "name": "I8",
    "kind": "integer",
    "size": 8,
    "signed": true,
}

Example JSON of I64

{
    "name": "I64",
    "kind": "integer",
    "size": 64,
    "signed": true,
}

Floating-Point Type Names

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 JSON of F32

{
    "name": "F32",
    "kind": "float",
    "size": 32,
}

Example JSON of F64

{
    "name": "F64",
    "kind": "float",
    "size": 64,
}

Boolean Type Name

Field	Description	Options	Required
name	String representing the FPP type name	bool	true
kind	String representing the kind of type	bool	true

Boolean Types

• true
• false

Example JSON of bool

{
    "name": "bool",
    "kind": "bool",
}

String Type Names

Field	Description	Options	Required
name	String representing the FPP type name	string	true
kind	String representing the kind of type	string	true
size	Number of bytes supported by the data type	Number in the range [0, 231)	true

String Types

Any sequence of characters

Example JSON of string

{
    "name": "string",
    "kind": "string",
    "size": 64,
}

Qualified Identifier Type Names

Field	Description	Options	Required
name	String representing the FPP type name	Period separated String	true
kind	String representing the kind of type	qualifiedIdentifier	true

Example JSON of qualified name

{
    "name": "M.a",
    "kind": "qualifiedIdentifier",
}

Type Definitions

Array Type Definition

Field	Description	Options	Required
kind	String representing the kind of type	array	true
qualifiedName	String representing unique qualified name of element in FPP model	Period separated String	true
size	Max Number of elements that can be in the data structure	Number	true
elementType	A JSON dictionary representing the type of array	JSON Dictionary	true
default	Default array value	Value of type specified in elementType	false

Example FPP model with JSON representation:

module M {
  array A = [3] U8
}

{
    "kind": "array",
    "qualifiedName": "M.A",
    "size": 3,
    "elementType": {
        "name": "U8",
        "kind": "integer",
        "signed": false,
        "size": 8
    },
    "default": [0, 0, 0]
}

Enumeration Type Definition

Field	Description	Options	Required
kind	String representing the kind of type	enum	true
qualifiedName	String representing unique qualified name of element in FPP model	Period separated String	true
representationType	The Type Name of values in the enumeration	Type Name	true
identifiers	Dictionary of identifiers (keys) and numeric values (values)	JSON Dictionary	true
default	String qualified name of the enumeration value	String qualified name	false

Example FPP model with JSON representation:

module M {
    enum Status {
        YES
        NO
        MAYBE
    } default MAYBE
}

{
    "kind": "enum",
    "qualifiedName": "M.Status",
    "representationType": {
        "name": "I32",
        "kind": "integer",
        "signed": true,
        "size": 32
    },    
    "identifiers": {
        "YES": 0, 
        "NO": 1,
        "MAYBE": 2
    },
    "default": "M.Status.MAYBE"
}

Struct Type Definition

Struct Member

Field	Description	Options	Required
type	Type Name of member	Type Name	true
index	Number index of the struct member	Number	true
size	Number representing the size of the struct member	Number	false
formatSpecifier	String format specifier	String	false

Struct Type Definition

Field	Description	Options	Required
kind	String representing the kind of type	struct	true
qualifiedName	String representing unique qualified name of element in FPP model	Period separated String	true
members	JSON dictionary consisting of String identifier (key) and Struct Member (value)	JSON dictionary	true
default	JSON dictionary consisting of String identifier (key) and default value (value)	JSON dictionary	false

Example FPP model with JSON representation:

module M {
    struct A {
        w: [3] U32
        x: U32
        y: F32
    }
}

{
    "kind": "struct",
    "qualifiedName": "M.A",
    "members": {
         "w": {
            "type": {
                "name": "M.A.w",
                "kind": "qualifiedIdentifier"
            },
            "index": 0,
            "size": 3
        },
        "x": {
            "type": {
                "name": "U32",
                "kind": "integer",
                "signed": false,
                "size": 32
            },
            "formatSpecifier": "the count is {}",
            "index": 1
        },
        "y": {
            "type": {
                "name": "F32",
                "kind": "float",
                "size": 32
            },
            "index": 2
        }
    },
    "default": {
        "w": [0, 0, 0],
        "x": 0,
        "y": 0
    },
}

Values

Primitive Integer Values

Number representing integer value

Example JSON of type U8 with a value of 2:

2

Example JSON of type I8 with a value of -2:

-2

Floating-Point Values

Number representing float value

Example JSON of type F32 with a value of 10.0

10.5

Boolean Values

Boolean value

Example JSON of type bool with a value of true

true

String Values

String containing sequence of characters

Example JSON of type string with a value of "Hello World!"

"Hello World!"

Array Values

Array with elements

Example JSON of an array of type U32 consisting of 10 elements

[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

Enumeration Values

String qualified identifier name of enumeration value

Example JSON of an enum

"Status.YES"

Struct Values

JSON Dictionary consisting of String qualified identifier names (keys) and values (values)

Example JSON of a struct:

{
    "S.w": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
    "S.x": 20,
    "S.y": "Hello World!",
    "S.z": 15.5
}

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

Parameters, Commands, Telemetry Channels, and Events

Formal Parameters

Field	Description	Options	Required
identifier	String identifier	String	true
description	String annotation of parameter	String	true
type	Type Name of parameter	Type Name	true
ref	Boolean indicating whether the formal parameter is to be passed by referenced when it is used in a synchronous port invocation	Boolean	false

{
    "identifier": "param1",
    "description": "Param 1",
    "type": {
        "name": "U32",
        "kind": "integer",
        "size": 32,
        "signed": false,
    },
    "ref": false
}

Parameters

Field	Description	Options	Required
identifier	String qualified name of the parameter	Period separated String	true
description	String annotation of parameter	String	true
type	Type Name of the parameter	Type Name	true
default	Default value (of type specified in type) of the parameter	Value of type specified in type	false
numericIdentifier	Number representing the numeric identifier of the parameter	Number	false
setOpcode	Number representing the opcode of the command for setting the parameter	Number	false
saveOpcode	Number representing the opcode of the command for saving the parameter	Number	false

Example FPP model with JSON representation:

module MyModule {
    active component FirstComponent {
        @ This is the annotation for Parameter 1
        param Parameter1: U32 \
            id 0x100 \
            set opcode 0x101 \
            save opcode 0x102
 
        ...
    }
}

{
    "identifier": "MyModule.FirstComponent.Parameter1",
    "description": "This is the annotation for Parameter 1",
    "type": {
        "name": "U32",
        "kind": "integer",
        "signed": false,
        "size": 32
    },
    "default": 0,
    "numericIdentifier": "256",
    "setOpcode": "257",
    "saveOpcode": "258"
}

Commands

Field	Description	Options	Required
identifier	String qualified name of the command	Period separated String	true
commandKind	String representing the kind of command	async, guarded, sync	true
opcode	Number command opcode	Number	true
description	String annotation of command	string	true
formalParams	Array of Formal Parameters	Array of Formal Parameters	true
priority	Number representing the priority for the command on the input queue	Number	false
queueFullBehavior	String representing the behavior of the command when the input full is queue	assert, block, drop	false

Example FPP model with JSON representation:

module MyComponents {
    active component FirstComponent {
        @ A sync command with parameters
        sync command SyncParams(
            param1: U32 @< Param 1
            param2: string @< Param 2
        ) opcode 0x100
        
        ...
    }
}

{
    "identifier": "MyComponents.FirstComponent.SyncParams",
    "commandKind": "sync",
    "opcode": 256,
    "description": "A sync command with parameters",
    "formalParams": [
        {
            "identifier": "param1",
            "description": "Param 1",
            "type": {
                "name": "U32",
                "kind": "integer",
                "size": 32,
                "signed": false,
            },
            "ref": false
        },
         {
            "identifier": "param2",
            "description": "Param 2",
            "type": {
                "name": "string",
                "kind": "string",
                "size": ""
            },
            "ref": false
        }
    ],
}

Telemetry Channels

Field	Description	Options	Required
identifier	String qualified name of the telemetry channel	Period separated String	true
description	String annotation of channel	String	true
type	Type Name the telemetry channel	Type Name	true
numericIdentifier	Number representing numeric identifier	Number	true
telemetryUpdate	String representing when the telemetry channel can update	always, on change	false
formatString	String format with a single argument (the telemetry channel)	String	false
limit	JSON dictionary consisting of low and high limits	JSON dictionary	false

Example FPP model with JSON representation:

module MyModule {
    active component FirstComponent {
        @ Telemetry channel 1
        telemetry Channel1: F64 \
            id 0x100 \
            update on change \
            low { yellow -1, orange -2, red -3 } \
            high { yellow 1, orange 2, red 3 }
        
        ...
    }
}

[
    {
        "identifier": "MyModule.FirstComponent.Channel1",
        "description": "Telemetry channel 1",
        "type": {
            "type": "F64",
            "kind": "float",
            "size": 64
        },
        "numericIdentifier": 256,
        "telemetryUpdate": "on change",
        "limit": {
            "low": {
                "yellow": -1,
                "orange": -2,
                "red": -3
            },
            "high": {
                "yellow": 1,
                "orange": 2,
                "red": 3
            }
        }
    }
]

Events

Field	Description	Options	Required
identifier	String qualified name of the event	Period separated String	true
description	String annotation of event	String	true
severity	String representing severity of the event	activity high, activity low, command, diagnostic, fatal, warning high, warning low	true
formalParams	Array of Formal Parameters	Array Formal Parameters	true
numericIdentifier	Number representing the numeric identifier of the event	Number	true
formatString	String format with event parameters as arguments	String	false
throttle	Number representing the maximum number of times to emit the event before throttling it	Number	false

Example FPP model with JSON representation:

module MyModule {
    active component FirstComponent {
        @ This is the annotation for Event 0
        event Event0 \
            severity activity low \
            id 0x100 \
            format "Event 0 occurred"
        
        ...
    }
}

{
    "identifier": "MyModule.FirstComponent.Event0",
    "description": "This is the annotation for Event 0",
    "severity": "activity low",
    "formalParams": [],
    "numericIdentifier": 256,
    "formatString": "Event 0 occurred",
}

Example FPP model with JSON representation:

module MyModule {
    active component FirstComponent {
        @ This is the annotation for Event 1
        @ Sample output: "Event 1 occurred with argument 42"
        event Event1(
            arg1: U32 @< Argument 1
        ) \
            severity activity high \
            id 0x101 \
            format "Event 1 occurred with argument {}"
        
        ...
    }
}

{
    "identifier": "MyModule.FirstComponent.Event1",
    "description": "This is the annotation for Event 1",
    "severity": "activity high",
    "formalParams": [
        {
           "identifier": "arg1",
            "description": "Argument 1",
            "type": {
                "name": "U32",
                "kind": "integer",
                "size": 32,
                "signed": false,
            },
            "ref": false  
        }
    ],
    "numericIdentifier": 257,
    "formatString": "Event 1 occurred with argument {}",
}

Data Products

Record

Field	Description	Options	Required
identifier	String qualified name of the record	Period separated String	true
description	String annotation of record	String	true
type	Type Name the record	Type Name	true
array	Boolean specifying whether the record stores a variable number of elements	Boolean	false
numericIdentifier	Number representing the numeric identifier of the record	Number	true

Example FPP model with JSON representation:

module MyModule {
    active component FirstComponent {
        @ Record 0: A variable number of F32 values
        @ Implied id is 0x100
        product record Record0: F32 array
 
        @ Record 1: A single U32 value
        product record Record1: U32 id 0x102
        
        ...
    }
}

[
    {
        "identifier": "MyModule.FirstComponent.Record0",
        "description": "Record 0: A variable number of F32 values",
        "type": {
            "name": "F32",
            "kind": "float",
            "size": 32
        },
        "array": true,
        "numericIdentifier": 256 
    },
    {
        "identifier": "MyModule.FirstComponent.Record1",
        "description": "Record 1: A single U32 value",
        "type": {
            "name": "U32",
            "kind": "integer",
            "signed": false,
            "size": 32
        },
        "array": false,
        "numericIdentifier": 258
    }      
]

Container

Field	Description	Options	Required
identifier	String qualified name of the container	Period separated String	true
description	String annotation of container	String	true
numericIdentifier	Number representing the numeric identifier of the record	Number	true
defaultPriority	Number representing the downlink priority for the container	Number	false

Example FPP model with JSON representation:

module MyModule {
    active component FirstComponent {
        @ Container 0
        @ Implied id is 0x100
        product container Container0
 
        @ Container 1
        product container Container1 id 0x102
 
        @ Container 2
        @ Implied id is 0x103
        product container Container2 default priority 10
 
        ...
    }
}

[
    {
       "identifier": "MyModule.FirstComponent.Container0",
       "description": "Container 0\nImplied id is 0x100",
       "numericIdentifier": 256,
    },
    {
        "identifier": "MyModule.FirstComponent.Container1",
        "description": "Container 1",
        "numericIdentifier": 258,
    },
    {
        "identifier": "MyModule.FirstComponent.Container2",
        "description": "Container 2\nImplied id is 0x103",
        "numericIdentifier": 3,
        "defaultPriority": 259
    }
]

Dictionaries

Dictionary Metadata

Field	Description	Options	Required
deploymentName	String representing the deployment name	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

{
    "deploymentName": "MyDeployment",
    "frameworkVersion": "3.3.2",
    "projectVersion": "1.0.0",
    "libraryVersions": []
}

Dictionary Content

Field	Description	Options	Required
metadata	Dictionary Metadata	Dictionary Metadata	true
arrays	Array of Arrays	Array of Arrays	true
enums	Array of Enums	Array of Enums	true
structs	Array of Structs	Array of Structs	true
commands	Array of Commands	Array of Commands	true
events	Array of Events	Array of Events	true
telemetryChannels	Array of Telemetry Channels	Array of Telemetry Channels	true
parameters	Array of Parameters	Array of Parameters	true

{
    "metadata": {
        "deploymentName": "MyDeployment",
        "frameworkVersion": "3.3.2",
        "projectVersion": "1.0.0",
        "libraryVersions": []
    },
    "enums": [
        {
            "kind": "enum",
            "qualifiedName": "MyDeployment.M.C1.Status",
            "representationType": {
                "name": "I32",
                "kind": "integer",
                "signed": true,
                "size": 32
            },    
            "identifiers": {
                "YES": 0, 
                "NO": 1,
                "MAYBE": 2
            },
            "default": "MyDeployment.M.C1.Status.MAYBE"
        }
    ],
    "arrays": [
        {
            "kind": "array",
            "qualifiedName": "MyDeployment.M.C1.A1",
            "size": 3,
            "elementType": {
                "name": "U8",
                "kind": "integer",
                "signed": false,
                "size": 8
            },
            "default": [0, 0, 0]
        },
        {
            "kind": "array",
            "qualifiedName": "MyDeployment.M.C1.A2",
            "size": 5,
            "elementType": {
                "name": "string",
                "kind": "string",
            },
            "default": ["a", "b", "c", "d", "e"]
        }
    ],
    "structs": [
        {
            "kind": "struct",
            "qualifiedName": "M.S1",
            "members": {
                "w": {
                    "type": {
                        "name": "MyDeployment.M.C1.S1.w",
                        "kind": "qualifiedIdentifier"
                    },
                    "index": 0,
                    "size": 3
                },
                "x": {
                    "type": {
                        "name": "U32",
                        "kind": "integer",
                        "signed": false,
                        "size": 32
                    },
                    "formatSpecifier": "the count is {}",
                    "index": 1
                },
                "y": {
                    "type": {
                        "name": "F32",
                        "kind": "float",
                        "size": 32
                    },
                    "index": 2
                }
            },
            "default": {
                "w": [0, 0, 0],
                "x": 0,
                "y": 0
            },
        },
        {
            "kind": "struct",
            "qualifiedName": "MyDeployment.M.C1.S2",
            "members": {
                "x": {
                    "type": {
                        "name": "string",
                        "kind": "string",
                    },
                    "formatSpecifier": "the string is {}",
                    "index": 0
                },
            },
            "default": {
                "w": "hello world!"
            },
        }
    ],
    "commands": [
        {
            "commandKind": "sync",
            "opcode": 257,
            "identifier": "MyDeployment.MyModule.FirstComponent.SyncParams",
            "description": "A sync command with parameters",
            "formalParams": [
                {
                    "identifier": "param1",
                    "description": "Param 1",
                    "type": {
                        "name": "U32",
                        "kind": "integer",
                        "size": 32,
                        "signed": false,
                    },
                    "ref": false
                },
                {
                    "identifier": "param2",
                    "description": "Param 2",
                    "type": {
                        "name": "string",
                        "kind": "string",
                        "size": ""
                    },
                    "ref": false
                }
            ],
        }
    ],
    "events": [
        {
            "identifier": "MyDeployment.MyModule.FirstComponent.Event0",
            "description": "This is the annotation for Event 0",
            "severity": "activity low",
            "formalParams": [
                {
                    "identifier": "",
                    "description": "",
                    "type": {},
                    "ref": false
                }
            ],
            "numericIdentifier": 256,
            "formatString": "Event 0 occurred",
            "throttle": ""
        },
        {
            "identifier": "MyDeployment.MyModule.FirstComponent.Event1",
            "description": "This is the annotation for Event 1",
            "severity": "activity high",
            "formalParams": [
                {
                "identifier": "arg1",
                    "description": "Argument 1",
                    "type": {
                        "name": "U32",
                        "kind": "integer",
                        "size": 32,
                        "signed": false,
                    },
                    "ref": false  
                }
            ],
            "numericIdentifier": 257,
            "formatString": "Event 1 occurred with argument {}",
            "throttle": ""
        }
    ],
    "telemetryChannels": [
        {
            "identifier": "MyDeployment.MyModule.FirstComponent.Channel1",
            "description": "Telemetry channel 1",
            "type": {
                "type": "F64",
                "kind": "float",
                "size": 64
            },
            "numericIdentifier": 256,
            "telemetryUpdate": "on change",
            "limit": {
                "low": {
                    "yellow": -1,
                    "orange": -2,
                    "red": -3
                },
                "high": {
                    "yellow": 1,
                    "orange": 2,
                    "red": 3
                }
            }
        }
    ],
    "parameters": [
        {
            "identifier": "MyDeployment.MyModule.FirstComponent.Parameter1",
            "description": "This is the annotation for Parameter 1",
            "type": {
                "name": "U32",
                "kind": "integer",
                "signed": false,
                "size": 32
            },
            "default": 0,
            "numericIdentifier": 256,
            "setOpcode": 257,
            "saveOpcode": 258
        }
    ]
}