Configure the SCHC Template (Advanced)

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 for detailed information on roles.

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

The JSON template can be sketched as follows:

templates
    |
    |----name
    |----youpi
    |----legacy
    |----(...)
    |----device SCHC rules
    |     |
    |     |----rule type
    |     |       |----compression rule
    |     |       |----rule ID
    |     |       |----flows
    |     |       |----(...)
    |     |       |----stack
    |     |       |      |----stack type
    |     |       |      |
    |     |
    |     |----rule type
    |     |       |----fragmentation rule
    |     |       |      |----direction
    |     |       |      |----fragmentation parameters
    |     |       |      |       |----mode
    |     |       |      |       |----(...)
    |     |       | 
    |     |       |----(...)
    |     |
    |     |----(...)
    |
    |----description
    |----(...)
    |----non matching rule
    |----SCHC template ID
    |----(...)
    |----payload pattern
    |       |----pattern rules
    |       |       |----pattern ID
    |       |       |----rule entries
    |       |       |----(...)
    |       | 
    |       |----(...)
    |

Example of a JSON Template

Click here to open an example of a JSON SCHC template in a new window

Common Parameters

The following parameters must be defined in the SCHC template at creation time:

Parameter	Value
name	The name of the SCHC template.
ruleIdSize	The size of the rule ID, in bits.
nonMatchingRule	The rule ID to use when a compression rule is 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 (at least one).

Each SCHC compression rule must include the following parameters:

• ruleType, which must be set to COMPRESSION_RULE.
• compressionRule, which contains a JSON object describing the rule.

'compressionRule'

compressionRule must have the following parameters:

Parameter	Value
ruleID	The ID of the rule, it must be unique per SCHC template.
flows	An array including only one JSON object describing the rule entries (see below the list of parameters for ruleEntries).
stack->stackType	The protocol stack type that will be compressed/decompressed with this rule. The supported stackType are: - IP4_UDP - IP4_UDP_COAP - IP6_UDP - IP6_UDP_COAP - IP4_UDP_DLMS - IP6_UDP_DLMS

'ruleEntries'

For each SCHC compression rule, the list of rule entries is described in the ruleEntries arrays of the flows array.

Each rule entry must contain the following parameters:

• fieldName: A list of Field Names is defined for each protocol layer (see below for the possible values).
• fieldLength: The length of the original field. It can be either a fixed value (in bits) if the length is known when the Rule is created or a type if the length is variable. The length of a header field is defined by its own protocol specification (e.g., IPv6 or UDP). If the length is variable, the type defines the process to compute the length and its unit (bits, bytes...).
• fieldPosition: In the case some fields might occur multiple times, the field position indicates which occurence it applies to.The default value is 1 and designates the first occurrence.
• matchingOperator: The supported Matching Operators (MO) are IGNORE, EQUAL, MSB or MATCHINDEX
• cdactionFunction: Compression/Decompression actions (see below for the possible values).
• targetValue: The value used to match against the packet header field. It can be a scalar value of any type (integer, strings, etc.) or a more complex structure (array, list, etc.).
• direction: The supported values are:
  • UP: SCHC compression rule for uplink only
  • DOWN: SCHC compression rule for downlink only
  • BI: SCHC compression rule for both uplink and downlink

'fieldName'

The supported values for fieldName are listed in the table below where each column corresponds to a protocol layer:

IPv4 Layer	IPv6 Layer	UDP Layer	COAP Layer	DLMS Wrapper Layer	Payload Compression
IP4_VERSION	IP6_VERSION	UDP_DEV_PORT	COAP_VERSION	DLMS_WRAPPER_VERSION	APP_PAYLOAD
IP4_IHL	IP6_TRAFFIC_CLASS	UDP_APP_PORT	COAP_TYPE	DLMS_WRAPPER_SSAP
IP4_TOS	IP6_FLOW_LABEL	UDP_LENGTH	COAP_TYPE	DLMS_WRAPPER_CSAP
IP4_LENGTH	IP6_LENGTH	UDP_CHECKSUM	COAP_CODE	DLMS_WRAPPER_LENGTH
IP4_ID	IP6_NEXT_HEADER		COAP_MSG_ID
IP4_FLAGS	IP6_HOP_LIMIT		COAP_TOKEN
IP4_FRAG_OFFSET	IP6_DEV_PREFIX		COAP_IF_MATCH
IP4_TTL	IP6_DEV_IID		COAP_URI_HOST
IP4_PROTOCOL	IP6_APP_PREFIX		COAP_ETAG
IP4_CHECKSUM	IP6_APP_IID		COAP_IF_NONE_MATCH
IP4_DEV_IP			COAP_OBSERVE
IP4_APP_IP			COAP_URI_PORT
			COAP_LOCATION_PATH
			COAP_URI_PATH
			COAP_CONTENT_FORMAT
			COAP_MAX_AGE
			COAP_URI_QUERY
			COAP_ACCEPT
			COAP_LOCATION_QUERY
			COAP_PROXY_URI
			COAP_PROXY_SCHEME
			COAP_SIZE1
			COAP_NO_RESP

'cdactionFunction'

The supported Compression/Decompression Actions (CDA) must be combined with Matching Operators as follows:

C/D Action	Combined with the Matching Operator
NotSent	IGNORE or EQUAL
ValueSent	IGNORE or EQUAL
MappingSent	MATCHINDEX
Lsb	MSB
ComputeUDPLength	IGNORE
ComputeUDPChecksum	IGNORE
DevIID	IGNORE
AppIID	IGNORE
ComputeIPv6Length	IGNORE
ComputeIP4Length	IGNORE
ComputeIP4HeaderLength	IGNORE
ComputeIP4Checksum	IGNORE
ComputeDLMSWrapperLength	IGNORE

info

The C/D action PatternSent is reserved for payload compression and must be combined with the APP_PAYLOAD field name.

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:

• ruleType, which must be set to FRAGMENTATION_RULE.
• fragmentationRule, which contains a JSON object describing the rule.

'fragmentationRule'

Parameter	Value
ruleID	The ID of the rule, it must be unique per SCHC template.
direction	The direction on which the fragmentation rule applies. The supported values are: - FRAG_UPLINK: For uplink packets - FRAG_DOWNLINK: For downlink packets - fragmentationParam: Contains 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
• The other for the downlink packets There is no BI value for the direction parameter in the case of fragmentation rules.

SCHC Fragmentation Modes

Standard

SCHC-LoRaWAN RFC recommends to use the ACK-on-Error mode for uplink and Ack-Always mode for downlink.

"fragmentationParam":
  {
    "mode":"<mode>"
    ...
  }

Four SCHC fragmentation modes are supported:

• NoACK
• ACKAlways
• ACKOnError
• OptimizedACK (Acklio's fragmentation mode)

See the SCHC by Acklio page for detailed information on fragmentation modes.

Refer to the description of the fragmentation mode parameters set in the Web interface to define the parameters in the JSON configuration file.

Payload Compression Rules

info

The Payload compression rules are applied only if one of the SCHC compression rules has a rule entry where:

• fieldName is set to APP_PAYLOAD
• cdaactionfunction is set to PatternSent

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 the ruleId for SCHC compression, this identifier is used to indicate the pattern rule applied to the packet.
• ruleEntries: Similar to the ruleEntries for the SCHC compression, this parameter lists the rule entries to apply to the payload, with the following limitations:
  • fieldName is always set to BYTES.
  • fieldLength cannot be set to 0, since variable length is not supported.
  • nonMatchingPatternId: Similar to the nonMatchingRule field for SCHC compression. This value is used when no Payload compression rule is matching.

SCHC Template Parameters

Inside a SCHC compression rule, it is possible to configure one or several Target Values (see ruleEntries) with a dynamic value.

They are called "Template Parameters" and will be defined later, once the device profile will be 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(), where GetMyParam is part of a list of predefined functions.
  For example GetDeviceIP6Prefix can be used to replace the Target Value by the device IPv6 Prefix Address.