Advanced SCHC Template Configuration
Roles
Only users with "Administrator" or "Multi-organization operator" roles are allowed to create SCHC Templates. Operators can only view templates
See Platform Management & Multi-Organization.
This page describes how to configure a SCHC Template using a JSON configuration file. Inside the JSON SCHC template, it is possible to fully describe:
- the SCHC compression/decompression rules
- the SCHC Fragmentation/Reassembly rules
- the Payload compression/decompression rules
Then, the template can be uploaded as described here.
JSON template example​
Below is an example of JSON template including:
- one SCHC Compression rule
- two SCHC Fragmentation rules (uplink and downlink)
- three Payload compression rules
{
"templates": [
{
"name": "my_template",
"youpi": [],
"legacy": false,
"unruly": false,
"ruleIdSize": 8,
"deviceSchcRules": [
{
"ruleType": "COMPRESSION_RULE",
"compressionRule": {
"ruleId": 28,
"flows": [
{
"flowId": 0,
"ruleEntries": [
{
"fieldName": "IP6_VERSION",
"fieldLength": 4,
"fieldPosition": 1,
"matchingOperator": {
"type": "EQUAL",
"value": 0
},
"cdactionFunction": "NotSent",
"targetValue": [
"6"
],
"direction": "BI"
},
{
"fieldName": "IP6_TRAFFIC_CLASS",
"fieldLength": 8,
"fieldPosition": 1,
"matchingOperator": {
"type": "IGNORE",
"value": 0
},
"cdactionFunction": "NotSent",
"targetValue": [
"0"
],
"direction": "BI"
},
{
"fieldName": "IP6_FLOW_LABEL",
"fieldLength": 20,
"fieldPosition": 1,
"matchingOperator": {
"type": "IGNORE",
"value": 0
},
"cdactionFunction": "NotSent",
"targetValue": [
"0x00012345"
],
"direction": "BI"
},
{
"fieldName": "IP6_LENGTH",
"fieldLength": 16,
"fieldPosition": 1,
"matchingOperator": {
"type": "IGNORE",
"value": 0
},
"cdactionFunction": "ComputeIPv6Length",
"targetValue": [
"0"
],
"direction": "BI"
},
{
"fieldName": "IP6_NEXT_HEADER",
"fieldLength": 8,
"fieldPosition": 1,
"matchingOperator": {
"type": "IGNORE",
"value": 0
},
"cdactionFunction": "NotSent",
"targetValue": [
"0x11"
],
"direction": "BI"
},
{
"fieldName": "IP6_HOP_LIMIT",
"fieldLength": 8,
"fieldPosition": 1,
"matchingOperator": {
"type": "IGNORE",
"value": 0
},
"cdactionFunction": "NotSent",
"targetValue": [
"64"
],
"direction": "BI"
},
{
"fieldName": "IP6_DEV_PREFIX",
"fieldLength": 64,
"fieldPosition": 1,
"matchingOperator": {
"type": "EQUAL",
"value": 0
},
"cdactionFunction": "NotSent",
"targetValue": [
"$GetDeviceIP6Prefix()"
],
"direction": "BI"
},
{
"fieldName": "IP6_DEV_IID",
"fieldLength": 64,
"fieldPosition": 1,
"matchingOperator": {
"type": "EQUAL",
"value": 0
},
"cdactionFunction": "NotSent",
"targetValue": [
"$GetDeviceIP6IID()"
],
"direction": "BI"
},
{
"fieldName": "IP6_APP_PREFIX",
"fieldLength": 64,
"fieldPosition": 1,
"matchingOperator": {
"type": "EQUAL",
"value": 0
},
"cdactionFunction": "NotSent",
"targetValue": [
"{{.ip6AppPrefix}}"
],
"direction": "BI"
},
{
"fieldName": "IP6_APP_IID",
"fieldLength": 64,
"fieldPosition": 1,
"matchingOperator": {
"type": "EQUAL",
"value": 0
},
"cdactionFunction": "NotSent",
"targetValue": [
"{{.ip6AppIid}}"
],
"direction": "BI"
},
{
"fieldName": "UDP_DEV_PORT",
"fieldLength": 16,
"fieldPosition": 1,
"matchingOperator": {
"type": "EQUAL",
"value": 0
},
"cdactionFunction": "NotSent",
"targetValue": [
"{{.devPort}}"
],
"direction": "BI"
},
{
"fieldName": "UDP_APP_PORT",
"fieldLength": 16,
"fieldPosition": 1,
"matchingOperator": {
"type": "EQUAL",
"value": 0
},
"cdactionFunction": "NotSent",
"targetValue": [
"{{.appPort}}"
],
"direction": "BI"
},
{
"fieldName": "UDP_LENGTH",
"fieldLength": 16,
"fieldPosition": 1,
"matchingOperator": {
"type": "IGNORE",
"value": 0
},
"cdactionFunction": "ComputeUDPLength",
"targetValue": [
"0"
],
"direction": "BI"
},
{
"fieldName": "UDP_CHECKSUM",
"fieldLength": 16,
"fieldPosition": 1,
"matchingOperator": {
"type": "IGNORE",
"value": 0
},
"cdactionFunction": "ComputeUDPChecksum",
"targetValue": [
"0"
],
"direction": "BI"
},
{
"fieldName": "APP_PAYLOAD",
"fieldLength": 0,
"fieldPosition": 1,
"matchingOperator": {
"type": "IGNORE",
"value": 0
},
"cdactionFunction": "PatternSent",
"targetValue": [
"0"
],
"direction": "BI"
}
]
}
],
"isDynamicContext": false,
"stack": {
"stackType": "IP6_UDP",
"displayName": "IPv6_UDP"
}
},
"fragmentationRule": null
},
{
"ruleType": "FRAGMENTATION_RULE",
"compressionRule": null,
"fragmentationRule": {
"direction": "FRAG_UPLINK",
"fragmentationParam": {
"mode": "ACKOnError",
"ruleIdSize": 8,
"dTagSize": 2,
"micAlgo": "CRC32_IEEE",
"tileSize": 32,
"wSize": 2,
"maxAck": 5,
"winSize": 63,
"maxWinFcn": 62,
"retransmissionTime": 300,
"all1RetransmissionTime": 300,
"inactivityTime": 80,
"disableAll1PayloadAoe": false,
"aoeSpecs": {
"disableAll1Payload": true,
"sendAckEveryWindow": false,
"disableBorrowPenultimateTile": false
},
"enableShortSessionRetransmissionTime": false,
"dTagReleaseTime": 0
},
"ruleId": 20
}
},
{
"ruleType": "FRAGMENTATION_RULE",
"compressionRule": null,
"fragmentationRule": {
"direction": "FRAG_DOWNLINK",
"fragmentationParam": {
"mode": "ACKOnError",
"ruleIdSize": 8,
"dTagSize": 2,
"micAlgo": "CRC32_IEEE",
"tileSize": 32,
"wSize": 2,
"maxAck": 5,
"winSize": 63,
"maxWinFcn": 62,
"retransmissionTime": 300,
"all1RetransmissionTime": 300,
"inactivityTime": 600,
"disableAll1PayloadAoe": false,
"aoeSpecs": {
"disableAll1Payload": true,
"sendAckEveryWindow": false,
"disableBorrowPenultimateTile": false
},
"enableShortSessionRetransmissionTime": false,
"dTagReleaseTime": 0
},
"ruleId": 21
}
}
],
"description": "",
"organization": "org1",
"createdBy": "martin",
"nonMatchingRule": 150,
"sCHCTemplateID": "11",
"syncRetry": null,
"syncInterval": null,
"payloadPattern": {
"patternRules": [
{
"patternId": 1,
"ruleEntries": [
{
"fieldName": "BYTES",
"fieldLength": 216,
"fieldPosition": 1,
"matchingOperator": {
"type": "EQUAL",
"value": 0
},
"cdactionFunction": "NotSent",
"targetValue": [
"0x16feff00000000000000000042010000360000000000000036fefd"
],
"direction": "BI"
},
{
"fieldName": "BYTES",
"fieldLength": 256,
"fieldPosition": 2,
"matchingOperator": {
"type": "IGNORE",
"value": 0
},
"cdactionFunction": "ValueSent",
"targetValue": [
"0x00"
],
"direction": "BI"
}
]
},
{
"patternId": 2,
"ruleEntries": [
{
"fieldName": "BYTES",
"fieldLength": 8,
"fieldPosition": 1,
"matchingOperator": {
"type": "EQUAL",
"value": 0
},
"cdactionFunction": "NotSent",
"targetValue": [
"0x20"
],
"direction": "BI"
},
{
"fieldName": "BYTES",
"fieldLength": 152,
"fieldPosition": 2,
"matchingOperator": {
"type": "EQUAL",
"value": 0
},
"cdactionFunction": "NotSent",
"targetValue": [
"0x000004ccab00ff010000080016000000170000"
],
"direction": "BI"
}
]
},
{
"patternId": 3,
"ruleEntries": [
{
"fieldName": "BYTES",
"fieldLength": 64,
"fieldPosition": 1,
"matchingOperator": {
"type": "EQUAL",
"value": 0
},
"cdactionFunction": "NotSent",
"targetValue": [
"0x17fefd0001000000"
],
"direction": "BI"
}
]
}
],
"nonMatchingPatternId": 150
}
}
]
}
Common parameters​
The following paramters must be defined in the SCHC template at creation time:
name: the name of the SCHC templateruleIdSize: the size of the rule ID, in bitsnonMatchingRule: the rule ID to be used when there is compression rule matching for a packet.sCHCTemplateID: the SCHC Template Identifier, used by the Synchronization service.
SCHC compression rules​
Based on RFC 8724 - Compression/Decompression section.
The SCHC compression rules are defined in the deviceSchcRules array. A SCHC template might contain several compression rules.
Each SCHC compression rule must include the following parameters:
ruleTypemust be set toCOMPRESSION_RULEcompressionRulecontaining a JSON object describing the ruleruleIDthe rule ID, it must be unique per SCHC templateflowsarray including only one JSON object which is describing the rule entriesstack->stackTypethe protocol stack type that we want to compress/decompress with this rule. The supportedstackTypeare:IP4_UDPIP4_UDP_COAPIP6_UDPIP6_UDP_COAPIP4_UDP_DLMSIP6_UDP_DLMS
Rule entries​
For each SCHC compression rule, the list of rule entries is described in the ruleEntries arrays.
Each rule entry must contain the following parameters:
fieldNamefieldLengthfieldPositionmatchingOperatorcdactionFunctiontargetValuedirection
Field Name​
fieldNameparameter
A list of Field Names is defined for each protocol layer. The supported Field Names are:
IPv4 layer:
IP4_VERSIONIP4_IHLIP4_TOSIP4_LENGTHIP4_IDIP4_FLAGSIP4_FRAG_OFFSETIP4_TTLIP4_PROTOCOLIP4_CHECKSUMIP4_DEV_IPIP4_APP_IP
IPv6 layer:
IP6_VERSIONIP6_TRAFFIC_CLASSIP6_FLOW_LABELIP6_LENGTHIP6_NEXT_HEADERIP6_HOP_LIMITIP6_DEV_PREFIXIP6_DEV_IIDIP6_APP_PREFIXIP6_APP_IID
UDP layer:
UDP_DEV_PORTUDP_APP_PORTUDP_LENGTHUDP_CHECKSUM
COAP layer:
COAP_VERSIONCOAP_TYPECOAP_TOKEN_LENCOAP_CODECOAP_MSG_IDCOAP_TOKENCOAP_IF_MATCHCOAP_URI_HOSTCOAP_ETAGCOAP_IF_NONE_MATCHCOAP_OBSERVECOAP_URI_PORTCOAP_LOCATION_PATHCOAP_URI_PATHCOAP_CONTENT_FORMATCOAP_MAX_AGECOAP_URI_QUERYCOAP_ACCEPTCOAP_LOCATION_QUERYCOAP_PROXY_URICOAP_PROXY_SCHEMECOAP_SIZE1COAP_NO_RESP
DLMS Wrapper layer:
DLMS_WRAPPER_VERSIONDLMS_WRAPPER_SSAPDLMS_WRAPPER_CSAPDLMS_WRAPPER_LENGTH
Payload compression:
APP_PAYLOAD
Matching Operator​
matchingOperatorparameter
The supported Matching Operators (MO) are:
IGNOREEQUALMSBMATCHINDEX
Compression/Decompression Actions​
cdactionFunctionparameter
The supported Compression/Decompression Actions (CDA) are:
NotSent(combined withIGNOREorEQUALMO)ValueSent(combined withIGNOREorEQUALMO)MappingSent(combined withMATCHINDEXMO)Lsb(combined withMSBMO)ComputeUDPLength(combined withIGNOREMO)ComputeUDPChecksum(combined withIGNOREMO)DevIID(combined withIGNOREMO)AppIID(combined withIGNOREMO)ComputeIPv6Length(combined withIGNOREMO)ComputeIP4Length(combined withIGNOREMO)ComputeIP4HeaderLength(combined withIGNOREMO)ComputeIP4Checksum(combined withIGNOREMO)ComputeDLMSWrapperLength(combined withIGNOREMO)PatternSent(reserved for payload compression - combined withAPP_PAYLOADfieldName)
SCHC Rule Direction​
The supported values are:
UP: SCHC compression rule for uplink onlyDOWN: SCHC compression rule for downlink onlyBI: SCHC compression rule for both uplink and downlink
SCHC fragmentation rules​
Based on RFC 8724 - Fragmentation/Reassembly section.
The SCHC fragmentation rules are defined in the deviceSchcRules array, when the value of ruleType is set to FRAGMENTATION_RULE.
Each SCHC fragmentation rule must include the following parameters:
ruleTypemust be set toFRAGMENTATION_RULEfragmentationRulecontaining a JSON object describing the ruleruleIDthe rule ID, it must be unique per SCHC templatedirectionthe direction on which this rules applies. The supported values are:FRAG_UPLINK: for the uplink packetsFRAG_DOWNLINK: for the downlink packets
fragmentationParamcontaining a JSON object describing the fragmentation parameters. This structure is described in the section below.
Fragmentation rules limitation
Only two fragmentation rules should be configured in the template: one for the uplink packets and the other for the downlink packets.
SCHC fragmentation modes​
"fragmentationParam":
{
"mode":"<mode>"
...
}
Three SCHC fragmentation modes are supported:
NoACKACKAlwaysACKOnError
Fragmentation configuration​
All the fragmentation modes and associated parameters can be configured directly by editing the SCHC template in the web interface.
Payload compression rules​
The Payload compression rules are defined in the payloadPattern->patternRules array.
Each Payload compression rule is defined as a new element in this array having the following parameters:
patternId: similar to theruleIdfor SCHC compression rules, it is an identified used to indicate the pattern rule applied to the packet.ruleEntries: as for the SCHC compressions rulesentries, it describes a list of rule entries we want to apply to the payload, with the following limitations:fieldNameis always set toBYTESfieldLengthcannot be set to 0 as varialble length filed is not supported
nonMatchingPatternId: similar to thenonMatchingRulefield for SCHC compression. This value is used when no Payload compression rule is matching.
info
The Payload compression rules are only applied if one of the SCHC compresssion rules contains a ryule entry with the fieldName set to APP_PAYLOAD and cdaactionfunction set to PatternSent.
SCHC template parameters​
Inside a SCHC compression rule, it is possible to configure one or several Target Values with a dynamic value. They are called Template Parameters and will be defined later, when the device profile is configured. There are two approaches to declare a SCHC Template Parameter:
- the Target Value can be set with the following syntax:
{{.<my_param_name>}}, where<my_param_name>is the name of the parameter. For instance{{.ip6AppPrefix}}in the template above allows the IPv6 prefix of the application to be configured in a device profile. - the Target Value can be set with a predefined function with the following syntax:
$GetMyParam(), whereGetMyParamis part of a list of predefined functions. For exampleGetDeviceIP6Prefixcan be used to replace the Target Value by the device IPv6 Prefix Address.