F´ Flight Software - C/C++ Documentation devel
A framework for building embedded system applications to NASA flight quality standards.
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
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
}
]
}