Conditional Byte
Dec 6 2023 at 12:00 AM
- Introduction
- Example Options File for ByteLength Condition
- Example Options File for ByteMask Condition
Introduction
This filter is designed to handle the byte array generated from the initial order filter payload data. It ensures that the payload is enriched with relevant properties based on the conditions met during processing. Additionally, it handles the inclusion of default properties to maintain a comprehensive payload structure. It adds properties to the payload following a specific set of conditions:
- Condition Evaluation: The filter begins by identifying the condition that evaluates to true.
- No True Condition: In the absence of a true condition, the filter logs this occurrence and exits.
- True Condition Processing: For the condition that evaluates to true, the filter retrieves the associated property values and incorporates them into the payload.
- Default Properties Check: If default properties are configured, the filter checks for any missing default properties on the payload. Any missing default properties are then added to the payload with their predefined default values.
 |
| It is advisable not to position this filter as the initial filter in the processing chain. Ideally, it should be placed as the second filter to ensure optimal functionality. |
Example Options File for ByteLength Condition
{
"Devices": {
"DemoDevice": {
"Enabled": true,
"Debug": true,
"DeviceType": "Generic",
"GroupName": "DemoDevice",
"ActionDelay": 60000,
"DataSource": {
"DataSourceType": "RestApi"
},
"Filters": [
{
"FilterType": "SigfoxParser",
"Order": 1,
"DeviceTypePath": "deviceTypeId",
"DeviceNamePath": "deviceId"
},
{
"FilterType": "ConditionalByte",
"Order": 2,
"DefaultProperties": {
"USBPower": {
"DataType": "Bool"
},
"BatteryVoltage": {
"DataType": "Int16"
}
},
"Conditions": {
"Trigger": {
"ConditionType": "ByteLength",
"ByteLength": 1,
"Properties": {
"USBPower": {
"DataType": "Bool",
"StartByte": 0
}
}
},
"Heartbeat": {
"ConditionType": "ByteLength",
"ByteLength": 4,
"Properties": {
"USBPower": {
"DataType": "Bool",
"StartByte": 1
},
"BatteryVoltage": {
"DataType": "Int16",
"StartByte": 2,
"LittleEndian": false
}
}
}
}
}
...
]
}
}
}
Property Details (Sigfox Parser)
Here is an overview of the parameters for configuring the Sigfox Parser filter:
First Order Filter (Sigfox Parser)
| Property Name | Description |
|---|---|
| FilterType | The value for this filter is “SigfoxParser”. |
| Order | Used to determine the process order when more than one filter has been configured. |
| GatewayIdPath | The JSON path for the property value that will be used for the gateway Id. If this is blank, then the configured gateway Id will be used. |
| GroupNamePath | The JSON path for the property value that will be used for the group name. If this is blank, then the configured group name will be used. |
| DeviceTypePath | The JSON path for the property value that will be used for the device type. If this is blank, then the configured device type will be used. |
| DeviceNamePath | The JSON path for the property value that will be used for the device name. If this is blank, then the configured device name will be used. |
Property Details (Conditional Byte)
Here is an overview of the parameters for configuring the Conditional Byte filter:
Second Order Filter (Conditional Byte)
| Property Name | Description |
|---|---|
| FilterType | The value for this filter is “ConditionalByte”. |
| Order | Used to determine the process order when more than one filter has been configured. |
| DefaultProperties | The default properties expected on the filter and their data types. |
| Conditions | The filter conditions that are evaluated to determine how to process the conditional byte. |
| Heartbeat (Condition name) | The name of the configured condition. |
| ConditionType | The Condition type. Currently only “ByteLength” and “ByteMask” condition type is supported. |
| ByteLength | The condition’s expected length of the byte array. If the data received byte array length is not equal to the expected byte array length, the condition will evaluate to false, thereby not processing the byte array. |
| Properties | The configured properties for the condition. |
| USBPower (Property name) | The configured property name. |
| DataType | The expected data type for the property. |
| StartByte | The starting byte position in the data byte array for the property. |
| LittleEndian | The Little-Endian is set to true by default. See to learn more. |
Example Options File for ByteMask Condition
{
"Devices": {
"TestDevice": {
"Enabled": true,
"Debug": true,
"DeviceType": "Generic",
"GatewayId": "GenericTestDevice",
"GroupName": "TestDevice",
"ActionDelay": 60000,
"DataSource": {
"DataSourceType": "RestApi"
},
"Filters": [
{
"FilterType": "SigfoxParser",
"Order": 1,
"DeviceTypePath": "deviceTypeId",
"DeviceNamePath": "deviceId"
},
{
"FilterType": "ConditionalByte",
"Order": 2,
"DefaultProperties": {
"TestProp1": {
"DataType": "Bool"
},
"TestProp2": {
"DataType": "Bool"
},
"TestProp3": {
"DataType": "Bool"
},
"TestProp4": {
"DataType": "Bool"
},
"TestProp5": {
"DataType": "Bool"
}
},
"Conditions": {
"TestCondition": {
"ConditionType": "ByteMask",
"Properties": {
"TestProp1": {
"DataType": "Bool",
"StartByte": 0,
"EndByte": 3,
"Masks": ["0x52","0x00","0x00","0x12"],
"ExpectedValues": [82,0,0,18]
},
"TestProp2": {
"DataType": "Bool",
"StartByte": 4,
"EndByte": 4,
"Masks": ["0x48"],
"ExpectedValues": [72]
},
"TestProp3": {
"DataType": "Bool",
"StartByte": 0,
"EndByte": 3,
"Masks": ["0x52","0x00","0x00","0x12"],
"ExpectedValues": [82,0,0,17]
},
"TestProp4": {
"DataType": "Bool",
"StartByte": 0,
"EndByte": 3,
"Masks": ["0x53","0x00","0x00","0x12"],
"ExpectedValues": [82,0,0,18]
},
"TestProp5": {
"DataType": "Bool",
"StartByte": 4,
"EndByte": 4,
"Masks": ["0xFF"],
"ExpectedValues": [72]
}
}
}
}
}
]
}
}
}
Property Details (Sigfox Parser)
Here is an overview of the parameters for configuring the Sigfox Parser filter:
First Order Filter (Sigfox Parser)
| Property Name | Description |
|---|---|
| FilterType | The value for this filter is “SigfoxParser”. |
| Order | Used to determine the process order when more than one filter has been configured. |
| GatewayIdPath | The JSON path for the property value that will be used for the gateway Id. If this is blank, then the configured gateway Id will be used. |
| GroupNamePath | The JSON path for the property value that will be used for the group name. If this is blank, then the configured group name will be used. |
| DeviceTypePath | The JSON path for the property value that will be used for the device type. If this is blank, then the configured device type will be used. |
| DeviceNamePath | The JSON path for the property value that will be used for the device name. If this is blank, then the configured device name will be used. |
Property Details (Conditional Byte)
Here is an overview of the parameters for configuring the Conditional Byte filter:
Second Order Filter (Conditional Byte)
| Property Name | Description |
|---|---|
| FilterType | The value for this filter is “ConditionalByte”. |
| Order | Used to determine the process order when more than one filter has been configured. |
| DefaultProperties | The default properties expected on the filter and their data types. |
| Conditions | The filter conditions that are evaluated to determine how to process the conditional byte. |
| TestCondition(Condition name) | The name of the configured condition. |
| ConditionType | The Condition type. Currently only “ByteLength” and “ByteMask” condition type is supported. |
| Properties | The configured properties for the condition. |
| TestProp1(Property name) | The configured property name. |
| DataType | The expected data type for the property. |
| StartByte | The starting byte position in the data byte array for the property. |
| EndByte | The index of the byte to end the masking. |
| Masks | Array of hexadecimal masks to apply to the bytes indicated by the start and end byte index. The masks will be applied in the order they are configured, and there should always be a mask per byte within the range of the start and end byte indicated. The masks should be added as strings in the 0x00 hexadecimal format. |
| ExpectedValues | Array of expected decimal values for the bytes after the masks are applied. By comparing value of the byte after the mask is applied, the boolean value for the property is determined. The values will be evaluated in the order they are configured, and there should always be a value per byte within the range of the start and end byte indicated. |
| LittleEndian | The Little-Endian is set to true by default. (Not included in config) See to learn more. |