Subsections of Control APIs

JSON RPC 2.0 API

This section describes the communication protocol between the control system and SDM using RPC calls using the JSON-RPC 2.0 protocol

Definitions

Caution

Commands must be formatted as defined in the JSON-RPC 2.0 protocol
All commands sent over TCP transport must end with <LF>
All replies are formatted as defined in the JSON-RPC 2.0 protocol
All replies over TCP transport end up with <LF>
<LF> stands for “line feed”, corresponding hex is 0x0A

Transport protocols

JSON-RPC 2.0 commands can flow over different transport protocols, once enabled in the api section of the config files. Per default they might not be enabled. Edid the config file to suite your needs and restart sdm service

Transport Config Datatype Example Supported Versions
TCP jrpc2TCPInterface string enp1s0 >v1.8.50
TCP jrpc2TCPPort int 64823 >v1.8.50
TCP jrpc2HTTPInterface string enp1s0 >v1.8.50
TCP jrpc2HTTPPort int 64880 >v1.8.50

In subsequent pages all methods are described that can be used.

Concurrency

All JSON-RPC 2.0 services do support asynchronous message processing. 3rd party control Systems must keep tracking of the id’s to determine whether a request was successful or not

TCP transport

Any TCP capable application can be used to test commands. Do not forget to end up with <LF>

HTTP transport

The body of the HTTP POST request must contain the complete JSON-RPC request message, encoded with Content-Type: application/json. Either a single request object or a list of request objects is supported. If the request completes, whether or not there is an error, the HTTP response is 200 (OK) for ordinary requests or 204 (No Response) for notifications, and the response body contains the JSON-RPC response. If the HTTP request method is not “POST”, SDM reports 405 (Method Not Allowed). If the Content-Type is not application/json, SDM reports 415 (Unsupported Media Type).

Test from a linux shell:
curl –header “Content-Type: application/json” –request POST –data ‘{“jsonrpc”:“2.0”,“id”:1,“method”:“sdm.Get”,“params”:{“property”:“version”}}’ http://host:64880

Subsections of JSON RPC 2.0 API

SDM

sdm.Get version

Get the running software version

Request

Method Param Value Comment Supported Versions
sdm.Get property version Property name to get >v1.8.50
​
{"jsonrpc":"2.0","id":1,"method":"sdm.Get","params":{"property":"version"}}

Reply

Result Comment
x.x.x Version of sdm installed
​
{"jsonrpc":"2.0","id":1,"result":"1.8.64"}

sdm.Get activation

Get the activation status

Request

Method Param Value Comment Supported Versions
sdm.Get property activation Property name to get >v1.8.50
​
{"jsonrpc":"2.0","id":1,"method":"sdm.Get","params":{"property":"activation"}}

Reply

Result Key Comment Supported Versions
Trial Deprecated >v1.8.70 <v1.8.70
IsTrial Is trial license is active? (deprecated >v1.8.70) <v1.8.70
License
Channels Allowed channels (unused)(deprecated >v1.8.70)
Devices Allowed devices
Gracetime Gracetime sdm runs with this license without online check
Exceed Time exceed since last online license check
Valid License if true, invalid if false
Expiration Timestamp for fixed expiration licenses (defaults to 2000-01-01T00:00:00Z -> ignored) >v1.8.72
Validation Timestamp of last online validation >v1.8.72
Refreshed License online refreshed since last start. If false license infomation may be invalid
​
{
	"jsonrpc": "2.0",
	"id": 1,
	"result": {
		"Trial": {
			"IsTrial": false
		},
		"License": {
			"Channels": 500,
			"Devices": 500,
			"Gracetime": 168,
			"Exceed": 0.002686415741388889,
			"Valid": true
			"Expiration":"2000-01-01T00:00:00Z"
			"Validation":"2021-09-10T16:47:08.452207569+02:00"
		},
		"Refreshed": true
	}
}

System

system.Get

log.level

Get the log level for sdm and associated processes

Request

Method Param Value Comment Supported Versions
system.Get property log.level Property name to get >v1.8.50
​
{"jsonrpc":"2.0","id":1,"method":"system.Get","params":{"property":"log.level"}}

Reply

Result Comment
x Active log level
​
{"jsonrpc":"2.0","id":1,"result":6}

system.Set

log.level

Set the log level for sdm and associated processes

Request

Method Param Value Comment Supported Versions
system.Set property log.level Property name to set >v1.8.50
level 0-7 Log level to set >v1.8.50
​
{"jsonrpc":"2.0","id":1,"method":"system.Set","params":{"property":"log.level","level":6}}

Reply

Result Comment
null null means acknowledged, no error
​
{"jsonrpc":"2.0","id":1,"result":null}

Config

config.Create

preset

Have sdm to create an example preset toml in the config directory. presets_config_example.toml will be created and can be modified and renamed as presets_config.toml. presets_config.toml is recognized by the system as file with preset definitions. See file content description for more info

Request

Method Param Value Comment Supported Versions
config.Create file presets_config_example.toml Example file to create >v1.8.67
​
{"jsonrpc":"2.0","id":1,"method":"config.Create","params":{"file":"presets_config_example.toml"}}

Reply

Result Comment
null null means acknowledged, no error
​
{"jsonrpc":"2.0","id":1,"result":null}

symnet

Have sdm to create symnet source and destination config examples in the config directory. Either symnet_config_sources_example.toml or symnet_config_destinations_example.toml will be created and can be renamed as symnet_config_sources.toml, symnet_config_destinations.toml

symnet_config_sources.toml is recognized by the system as file with source definitions. See file content description for more info symnet_config_destinations.toml is recognized by the system as file with destination definitions. See file content description for more info

Request

Method Param Value Comment Supported Versions
config.Create file symnet_config_sources_example.toml Example file to create >v1.8.67
symnet_config_destinations_example.toml Example file to create >v1.8.67
​
{"jsonrpc":"2.0","id":1,"method":"config.Create","params":{"file":"symnet_config_sources_example.toml"}}
​
{"jsonrpc":"2.0","id":1,"method":"config.Create","params":{"file":"symnet_config_destinations_example.toml"}}

Reply

Result Comment
null null means acknowledged, no error
​
{"jsonrpc":"2.0","id":1,"result":null}

Preset

preset.Recall

Recall a preset defined in presets_config.toml. presets_config.toml is recognized by the system as file with preset definitions. See file content description for more info

Request

Method Param Value Comment Supported Versions
preset.Recall preset 1-x Preset to recall >v1.8.67
​
{"jsonrpc":"2.0","id":1,"method":"preset.Recall","params":{"preset":1}}

Reply

Result Comment
null null means acknowledged, no error
​
{"jsonrpc":"2.0","id":1,"result":null}

Monitor

monitor.Get

status

Request a status from monitoring, like PTP states from Dante™

Request

Method Param Value Comment Supported Versions
monitor.Get status clocking Status to get >v1.8.50
​
{"jsonrpc":"2.0","id":1,"method":"monitor.Get", "params":{"status": "clocking"}}

Reply

​
{
	"jsonrpc": "2.0",
	"id": 1,
	"result": {
		"SDM-DEV-DSP1-4": {
			"Preferred": 0,
			"Mutes": {},
			"Ports": {
				"1": {
					"PortState": "PASSIVE",
					"PathType": "MULTICAST",
					"Layer": "LAYER3",
					"LinkDown": 0,
					"PtpVersion": 1,
					"InterfaceIndex": 2
				},
				"2": {
					"PortState": "SLAVE",
					"PathType": "MULTICAST",
					"Layer": "LAYER3",
					"LinkDown": 0,
					"PtpVersion": 2,
					"InterfaceIndex": 2
				},
				"3": {
					"PortState": "DISABLED",
					"PathType": "UNICAST",
					"Layer": "LAYER3",
					"LinkDown": 0,
					"PtpVersion": 1,
					"InterfaceIndex": 2
				},
				"4": {
					"PortState": "DISABLED",
					"PathType": "UNICAST",
					"Layer": "LAYER3",
					"LinkDown": 0,
					"PtpVersion": 2,
					"InterfaceIndex": 2
				}
			}
		},
		"SDM-DEV-DSP2-1": {
			"Preferred": 0,
			"Mutes": {},
			"Ports": {
				"1": {
					"PortState": "PASSIVE",
					"PathType": "MULTICAST",
					"Layer": "LAYER3",
					"LinkDown": 0,
					"PtpVersion": 1,
					"InterfaceIndex": 2
				},
				"2": {
					"PortState": "SLAVE",
					"PathType": "MULTICAST",
					"Layer": "LAYER3",
					"LinkDown": 0,
					"PtpVersion": 2,
					"InterfaceIndex": 2
				},
				"3": {
					"PortState": "DISABLED",
					"PathType": "UNICAST",
					"Layer": "LAYER3",
					"LinkDown": 0,
					"PtpVersion": 1,
					"InterfaceIndex": 2
				},
				"4": {
					"PortState": "DISABLED",
					"PathType": "UNICAST",
					"Layer": "LAYER3",
					"LinkDown": 0,
					"PtpVersion": 2,
					"InterfaceIndex": 2
				}
			}
		}
	}
}

Discovery

discovery.Get

media

Get all discovered Dante™ devices

Request

Method Param Value Comment Supported Versions
discovery.Get type media Type for Dante™ is “media” >v1.8.50
domain ADHOC Dante domain, may be used in future versions
​
{"jsonrpc":"2.0","id":1,"method":"discovery.Get","params":{"domain":"ADHOC","type":"media"}}

Reply

Result Comment
Map of all Dante devices discovered
​
{"jsonrpc":"2.0","id":1,"result":["SDM-DEV-XIN1-3","SDM-DEV-DSP2-1","SDM-DEV-DSP1-4"]}

sdp

Get all discovered sdp sending devices, mostly these are AES67 compatible devices

Request

Method Param Value Comment Supported Versions
discovery.Get type sdp Type for AES67 is “sdp” >v1.8.50
domain ADHOC Dante domain, may be used in future versions
​
{"jsonrpc":"2.0","id":1,"method":"discovery.Get","params":{"domain":"ADHOC","type":"sdp"}}

Reply

Result Comment
Map of all Dante AES67 flows announced
​
{"jsonrpc":"2.0","id":1,"result":["239.69.40.217@SDM-Test","239.69.40.179@SDM-Foo"]}

Server

This section describes the communication protocol between the control system and SDM

rpc.serverInfo

Get all supported RCP methods

Request

Method Param Value Comment Supported Versions
rpc.serverInfo >v1.8.50
​
{"jsonrpc":"2.0","id":1,"method":"rpc.serverInfo"}

Reply

Result Key Comment
methods All supported methods that can be used by a 3rd party control system
counters Server counters
startTime Server start time
​
{
	"jsonrpc": "2.0",
	"id": 1,
	"result": {
		"methods": ["config.Create", "discovery.Get", "monitor.Get", "preset.Recall", "routing.Create", "routing.Delete", "routing.Get", "routing.Subscribe", "sdm.Get", "system.Get", "system.Set"],
		"usesContext": false,
		"counters": {
			"rpc.bytesRead": 50,
			"rpc.requests": 1
		},
		"maxValue": {
			"rpc.bytesRead": 50
		},
		"startTime": "2021-04-22T06:19:41.709283225Z"
	}
}

Routing

routing.Get

rxchannels

Get all received channels from a Dante™ device

Request

Method Param Value Comment Supported Versions
routing.Get name string Name of the device >v1.8.50
component rxchannels >v1.8.50
domain ADHOC Dante domain, may be used in future versions
​
{"jsonrpc":"2.0","id":2,"method":"routing.Get","params":{"name":"SDM-DEV-DSP1-4","domain":"ADHOC","component":"rxchannels"}}

Reply

Result Key Comment
channels (map) Receiving channels 1-x
canonicalName Channel canonical name
label Channel label name
subscriptedLabel Channel label from channel that is received
subscriptedDevice Device name from which the channel is received
Name Device name
​
{
	"jsonrpc": "2.0",
	"id": 2,
	"result": {
		"channels": {
			"1": {
				"canonicalName": "Zone_Channels-Ch1",
				"label": "Zone_Channels-Ch1",
				"subscriptedLabel": "NONE",
				"subscriptedDevice": "NONE"
			},
			"21": {
				"canonicalName": "Zone_Channels-Ch21",
				"label": "Zone_Channels-Ch21",
				"subscriptedLabel": "Source_Channels-Ch45",
				"subscriptedDevice": "SDM-DEV-DSP1-4"
			}
		},
		"Name": "SDM-DEV-DSP1-4"
	}
}

routing.Get

txchannels

Get all sent channels from a Dante™ device

Request

Method Param Value Comment Supported Versions
routing.Get name string Name of the device >v1.8.50
component txchannels >v1.8.50
domain ADHOC Dante domain, may be used in future versions
​
 {"jsonrpc": "2.0","id":2,"method": "routing.Get","params":{"name":"SDM-DEV-DSP1-4","domain":"ADHOC","component":"txchannels"}}

Reply

Result Key Comment
channels (map) Transmitting channels 1-x
canonicalName Channel canonical name
labels Channel labels (map)
Name Device name
​
{
	"jsonrpc": "2.0",
	"id": 2,
	"result": {
		"channels": {
			"1": {
				"canonicalName": "01",
				"labels": {
					"0": "Source_Channels-Ch1"
				}
			},
			"10": {
				"canonicalName": "10",
				"labels": {
					"0": "Source_Channels-Ch10"
				}
			}
		},
		"Name": "SDM-DEV-DSP1-4"
	}
}

txflows

Get all sent flows from a Dante™ device

Request

Method Param Value Comment Supported Versions
routing.Get name string Name of the device >v1.8.50
component txflows >v1.8.50
domain ADHOC Dante domain, may be used in future versions
​
{"jsonrpc": "2.0","id":2,"method": "routing.Get","params":{"name":"SDM-DEV-DSP1-4","domain":"ADHOC","component":"txflows"}}

Reply

Result Key Sub Comment
flows (map) Transmitting flows 1-x
name Flow name
Slots Flow slots (map)
ChannelName Name of the channel
ChannelID Channel ID
ID Flow ID
Interfaces How many interfaces are used for this flow
Addresses Flow Addresses (map)
Addr Multicast IP Address
Port Port
FlowClass 1=Dante&trade, 2,3=AES67, 4=RTP
Aes67OrigAddress AES67 original address if AES67
Transport AES67 or Dante
DestDevice Destination device the flow flows to if unicast
Flow ID Destination flow name on the device the flow flows to if unicast
Name Device name
​
{
	"jsonrpc": "2.0",
	"id": 2,
	"result": {
		"flows": {
			"0": {
				"name": "Source_Channels",
				"indexes": null,
				"Slots": {
					"0": {
						"ChannelName": "Source_Channels-Ch1",
						"ChannelID": 1
					},
					"1": {
						"ChannelName": "Source_Channels-Ch2",
						"ChannelID": 2
					}
				},
				"ID": 1,
				"Interfaces": 1,
				"Addresses": {
					"0": {
						"Addr": "239.255.105.118",
						"Port": 4321
					}
				},
				"FlowClass": 1,
				"Aes67OrigAddress": "",
				"Transport": "DANTE",
				"DestDevice": "",
				"DestFlow": ""
			}

		},
		"Name": "SDM-DEV-DSP1-4"
	}
}

rxflows

Get all received flows from a Dante™ device

Request

Method Param Value Comment Supported Versions
routing.Get name string Name of the device >v1.8.50
component rxflows >v1.8.50
domain ADHOC Dante domain, may be used in future versions
​
{"jsonrpc": "2.0","id": 2,"method": "routing.Get","params":{"name":"SDM-DEV-DSP1-4","domain": "ADHOC","component":"rxflows"}}

Reply

Result Key Sub Comment
flows (map) Transmitting flows 1-x
name Flow name
Slots Flow slots (map)
Channels (map) Map of the channels received in this flow slot
ID Flow ID
Interfaces How many interfaces are used for this flow
Addresses Flow Addresses (map)
Addr Multicast IP Address
Port Port
FlowClass 1=Dante&trade, 2,3=AES67, 4=RTP
Aes67OrigAddress AES67 original address if AES67
Transport AES67 or Dante
Name Device name
​
{
	"jsonrpc": "2.0",
	"id": 2,
	"result": {
		"flows": {
			"0": {
				"name": "",
				"Slots": {
					"0": {
						"Channels": {
							"0": "Zone_Channels-Ch51"
						}
					},
					"1": {
						"Channels": {
							"0": "Zone_Channels-Ch52"
						}
					}
				},
				"ID": 1,
				"Interfaces": 1,
				"Addresses": {
					"0": {
						"Addr": "239.69.40.217",
						"Port": 5004
					}
				},
				"FlowClass": 1,
				"Aes67OrigAddress": "",
				"Transport": "Dante"
			},

			"2": {
				"name": "",
				"Slots": {
					"0": {
						"Channels": {
							"0": "Zone_Channels-Ch1"
						}
					},
					"1": {
						"Channels": {
							"0": "Zone_Channels-Ch2"
						}
					}
				},
				"ID": 3,
				"Interfaces": 1,
				"Addresses": {
					"0": {
						"Addr": "239.69.2.156",
						"Port": 5004
					}
				},
				"FlowClass": 2,
				"Aes67OrigAddress": "239.69.2.156",
				"Transport": "AES67"
			}
		},
		"Name": "SDM-DEV-DSP1-4"
	}
}

routing.Create

Create a new routing from a Dante™ or AES67 device to a a Dante™ device

Request

Method Param Sub-table key Comment Supported Versions
routing.Create tx channelName Source channel label/name/canonical name >v1.8.50
nodeName Source node name >v1.8.50
aesFlowName Source flow name >v1.8.67
aesFlowSlotID Slot ID of flow >v1.8.67
rx destination Destination channel label/name/canonical name >v1.8.50
nodeName Destination node name >v1.8.50
Info

Include node name to create a new routing

Even if it is allowed to create a new routing only based on the channel name, it is better to include the device name. The changeover is done more quickly

​
{
   "jsonrpc":"2.0",
   "id":1,
   "method":"routing.Create",
   "params":[
      {
         "rx":{
            "channelName":"Zone_Channels-Ch10"
         },
         "tx":{
            "channelName":"Source_Channels-Ch10"
         }
      }
   ]
}
​
{
   "jsonrpc":"2.0",
   "id":1,
   "method":"routing.Create",
   "params":[
      {
         "rx":{
            "nodeName":"SDM-DEV-DSP1-4",
            "channelName":"Zone_Channels-Ch10"
         },
         "tx":{
            "nodeName":"SDM-DEV-DSP1-4",
            "channelName":"Source_Channels-Ch10"
         }
      }
   ]
}
​
{
   "jsonrpc":"2.0",
   "id":1,
   "method":"routing.Create",
   "params":[
      {
         "tx":{
            "nodeName":"",
            "channelName":"Zone_Channels-Ch10"
         },
         "tx":{
            "aesFlowName":"239.69.40.217@Test-BTI",
            "aesFlowSlotID":1
         }
      },
      {
         "rx":{
            "nodeName":"",
            "channelName":"Zone_Channels-Ch11"
         },
         "rx":{
            "aesFlowName":"239.69.40.217@Test-BTI",
            "aesFlowSlotID":2
         }
      }
   ]
}

Reply

Result
null null means acknowledged, no error
​
{"jsonrpc":"2.0","id":1,"result":null}

routing.Delete

Delete a routing from a Dante™ or AES67 device to a a Dante™ device

Request

Method Param Sub-table key Comment Supported Versions
routing.Delete rx Destination Destination channel label/name/canonical name >v1.8.50
nodeName Destination node name >v1.8.50
Info

Include node name to delete routing

Even if it is allowed to delete a routing only based on the channel name, it is better to include the device name. The disconnect is done more quickly

​
{
   "jsonrpc":"2.0",
   "id":1,
   "method":"routing.Delete",
   "params":[
      {
         "RX":{
            "ChannelName":"Zone_Channels-Ch11"
         }
      }
   ]
}
​
{
   "jsonrpc":"2.0",
   "id":1,
   "method":"routing.Delete",
   "params":[
      {
         "RX":{
            "NodeName":"SDM-DEV-DSP1-4",
            "ChannelName":"Zone_Channels-Ch11"
         }
      }
   ]
}

Reply

Result
null null means acknowledged, no error
​
{"jsonrpc": "2.0","id": 1,"result": null}