Indigresso Wiki

Open Source Stuff for DASH7

User Tools

Site Tools


dash7_mode_2:registry_guide

Guide to DASH7 Registry

DASH7 Mode 2 specifies an integrated filesystem. The filesystem contains a number of required and reserved files that are used by the implementation of the standard (such as OpenTag) to configure functionality of the Physical, Data Link (MAC), and upper layers. Each implementation may have its own methods of setting or changing the data in these configuration files, and the DASH7 Mode 2 standard allows pre-configuring of settings (e.g. at compile time) or run-time configuring of settings.

Parts of the Registry

The registry is stored in the ISFB (Indexed Short File Block), primarily in file IDs 0 to 15. There are additionally some files defined between 16-24 (0x10-0x18), and these IDs are reserved, but they are completely optional.

Core Registry

The “core registry” is a group of files in the bottom of the ISFB that are very fundamental for configuration of the data link layer and other related parts of a DASH7 implementation. It contains the ISFB files shown in the table below.

Core Registry ISFB Files
ID Description Notes
0 Network Settings Contains dynamic DLL/MAC configuration settings
1 Device Features Generally read-only, describing device capabilities & limitations
2 Channel Configuration Contains list of available channels, and usage requirements
3 Real Time Scheduler Optional, but needed to implement reliable TDMA
4 Sleep Scan Series Channel scan sequence used during Sleep state
5 Hold Scan Series Channel scan sequence used during Hold state
6 Beacon Transmit Series Beacon transmit sequence used during idle periods (Sleep or Hold)

Extended Registry

The Extended Registry is also at the bottom of the ISFB, but just above the Core Registry. The Extended Registry is mostly optional, and mostly used for identification purposes rather than configuration. In other words, a device (A) can query files in another device's (B) extended registry to learn about application-oriented features that device B has enabled. Therefore, it is mostly for informational purposes.

Extended Registry ISFB Files
ID Description Notes
7 Protocol List A list of ALP IDs the device supports
8 ISSB File ID List A list of ISSB IDs (File IDs) that are included on the device
9 GFB File ID List A list of GFB IDs (File IDs) that are included on the device
10 Location Data List A data format and allocation for location applications to use
11 IPv6 Addresses Allocation for storage of Unicast, Multicast, Anycast IPv6 addresses
12 Sensor List A list of ISO 21451-7 TEDs elements, one for each sensor on the device
13 Sensor Alarm List A list of ISO 21451-7 Alarm elements, one for each sensor on the device
14 Root Authentication Key A Root-user cryptographic key – not readable or writable except by root
15 User Authentication Key An Admin-user cryptographic key – not readable or writeable except by admin/root

Legacy Registry

The legacy registry is defined in Mode 1, and Mode 2 devices may optionally include this part of the registry if there is desire to interoperate with Mode 1 networks, or if the Mode 2 devices do not need to interoperate with Mode 1, but are deployed for transportation logistics applications (for which Mode 1 is specifically intended).

Extended Registry ISFB Files
ID Description Notes
16 Routing Code An ISO-compliant routing code (text) for transportation logistics
17 ISSB File ID List An ISO-compliant User ID (text) for transportation logistics
18 Unused Unsupported Mode 1 table features
19
20
21
22 Hardware Fault Status Contains bitfields showing number of cold-boots and other system error flags

Working with the Core Registry

The Extended Registry and Legacy Registry do not really impact the behavior of the DASH7 lower layers, as they are chiefly data containers to provide some consistency for application developers. The Core Registry, however, impacts the way a DASH7 device works and behaves at a fundamental level. Changing values in the Core Registry can have profound effects on the Data Link Layer, turning a device into a classic active RFID tag, a WSN node, a TDMA communications device, or any kind of hybrid in between. Understanding how to use the Core Registry is of the utmost importance for DASH7 system integrators.

Network Settings (ISF 00)

This file contains variables useful for configuring the way a device interacts with the network. A network administrator may change these values, on a given host, to alter its usage of the network.

Default Permissions
root: rw- / user: rw- / guest: r–

Length: 10 bytes
Allocation: 10 bytes

Data Element Bytes Offset Description
VID 2 0 The Device Virtual ID (unused = 0xFFFF)
Device Subnet 1 2 Subnet value used to filter received packets
Beacon Subnet 1 3 Subnet value sent in automated beacons
Active Settings 2 4 Settings bits for current network behavior (see below)
Default Frame Config 1 6 Default header flags applied to outgoing Foreground frames (see below)
Beacon Redundancy 1 7 Number of sequential packet transmissions per beacon event (0 disables)
Hold Scan Series Cycles 2 8 Number of Hold Scan Series during Endpoint's Hold State
Settings Selector (used in Active Settings)
Field Position Description
Sleep Scheduler b15 Enables RTC Scheduling of Sleep Scan Series
Hold Scheduler b14 Enables RTC Scheduling of Hold Scan Series
Beacon Scheduler b13 Enables RTC Scheduling of Beacon Transmit Series
RFU b12
Gateway b11 Selects active device mode (only one may be set)
Subcontroller b10
Endpoint b9
RFU b8
3/4/5-way Transfer b7 3/4/5-way datastream transfers are permitted
2-way Transfer b6 2-way datastream transfers are permitted
FEC TX b5 FEC is enabled for TX
FEC RX b4 FEC is enabled for RX
RFU b3
Hi-Rate Channels b2 200 kS/s channels are enabled
Standard Channels b1 55 kS/s channels are enabled
RFU b0
Default Frame Config Bit Field
Field Position Description
Listen b7 Default outgoing frames have Listen Frame Control bit set
DLLS b6 Data Link Layer Security is used by default in outgoing frames
VID b5 Virtual ID is used by default for addressing in outgoing frames
NLS b4 Network Layer Security is used by default in outgoing frames
RFU b3-0

Settings Selector Typical Usage

The Setting Selector element is big endian, and the documentation is written that b15 is the most significant bit. The 2-byte field is always stored in big endian format. For a simple endpoint, the hex value (big endian) might be 0206h. For a sophisticated Subcontroller, the value might be 44F6h.

Default Frame Config Typical Usage

Typical value for default frame config is 0. For “closed-loop” networks, VID can be set to reduce the length of the frames. For networks with security requirements, the DLLS and NLS bits can be set. Listen bit is rarely set by default, although it can be enabled in order to implement creative types of functionality.

Device Features (ISF 01)

The Device Parameters ISFB file contains information about what the device can and cannot do. It is also where the UID is stored. “Available Memory” registers report the amount of unallocated memory in their respective data heaps. The Element also contains the name of the firmware, which may be important to data operations as the standard does not impose strict specifications on file system capability.

Default Permissions
root: rw- / user: r– / guest: r–

Length: 48 bytes
Allocation: 48 bytes

Data Element Bytes Offset Description
UID 8 0 The Device Unique ID
Supported Settings 2 8 Settings bits for all available features (see below)
Max Frame Length 1 10 Maximum value of Frame Length field (125-255)
Max Frames Per Packet 1 11 Maximum contiguous frames in a single packet (often HW dependent)
DLLS Available Methods 2 12 Bitmask selector of supported DLLS security/crypto methods (TBD)
NLS Available Methods 2 14 Bitmask selector of supported NLS security/crypto methods (TBD)
Total ISFB Memory 2 16 Bytes allocated to ISFB heap
Available ISFB Memory 2 18 Bytes free in ISFB heap
Total ISSB Memory 2 20 Bytes allocated to ISSB heap
Available ISSB Memory 2 22 Bytes free in ISSB heap
Total GFB Memory 2 24 Bytes allocated to GFB heap
Available GFB Memory 2 26 Bytes free in GFB heap
GFB File Size 2 28 Size in bytes of a GFB file (all GFB files are the same size)
RFU 1 30 RFU, set to 0
Session Stack Depth 1 31 Depth of Session Stack (1-255)
Firmware & Version 16 32 A Null-Terminated text string (UTF-8)

Usage: Supported Settings

The “Supported Settings” selector field is the same as the one use in the Network Settings file above. The value of the Supported Settings is at least the same as the value of the Active Setting field. In Supported Settings, multiple device types (i.e. Endpoint, Subcontroller, Gateway) can be set, as long as the device is implemented to support that functionality. Likewise, any other features that the device is designed to support should be selected in the Supported Settings. Whether the features are used or not is the data that belongs in the Active Settings field of the Network Settings file.

Usage: DLLS/NLS Available Methods

The DLLS and NLS technologies for DASH7 Mode 2 have not been standardized yet. At the moment, usage of these field is proprietary, but it should be some type of bitmask that indicates which types of secure exchange and/or cryptographic algorithms the device is designed to support.

Usage: File Block Memory Fields

The Total Memory fields for ISFB/ISSB/GFB can be hard-coded into the device in most cases, as these amounts are determined during compile-time or time of manufacture, and they never change. The Available Memory fields need to change whenever a file is added or deleted from the respective file block. For devices that do not support adding or deleting files, these fields also can be fixed at compile-time or time of manufacture.

Usage: Session Stack Depth

The DASH7 session layer is the method for managing dialogs and prioritizing dialogs. The Session layer maintains a sorted stack, and each element in the stack can contain information about a dialog that is scheduled to occur immediately or some time in the future. A bigger session stack can mean that more sophisticated dialog models are supported. In most cases, a session stack larger than 8 is completely unnecessary. A session stack of size 4 is quite common in implementation. Practical minimum size is 2. This value is determined during compile-time or time of manufacture, and it can be hard-coded into this file.

Usage: Firmware & Version

This field is a proprietary text field. OpenTag uses a version header like “OTvXXX” then a space and finally eight characters of Base64 encoded data. The 6 bytes of decoded, raw binary data include a 2 byte build integer and a 4 byte compiled-in features manifest. When building OpenTag firmware, this value is automatically determined and written to the file at the time of compiling. You can change the version (XXX) if you like.

Channel Configuration (ISF 02)

This file contains list of utilized transport channels and their configuration parameters. Ordering of the list is not required. The device may only communicate on channels contained in this list. However, a device may support channels not included in the list at any given time.

Default Permissions
root: rw- / user: rw- / guest: r–

Length: 8 bytes per utilized channel
Allocation: Minimum 64 bytes

Data Element Bytes Offset Description
Channel Spectrum ID 1 0 A byte-code containing center frequency and modulation info (see PHY)
Channel Parameters 1 1 see below
Channel TX Power Limit 1 2 see below
Link Quality Filter Level 1 3 see below
CS RSSI Level 1 4 Minimum RSSI for Carrier Sense Validation
CCA RSSI Level 1 5 Maximum RSSI for Clear-Channel-Assesment
Regulatory Code 1 6 see below
TX Duty Cycle 1 7 TX Duty Cycle, written as percentage (1-100)

Channel Parameters

The Channel Parameters field is used by devices that support TX-power autoscaling. TX-power autoscaling is optional, and not commonly implemented. If not implemented, this field can be ignored.

Channel Parameters Bitfield
Bitfield Position Description
Autoscale Enable b7 Set this bit to enable Autoscaling features on the device (if implemented)
Autoscale ID b3:0 4-bit algorithm type for Autoscaling. Currently undefined (proprietary)

Channel TX Power Limit

The Channel TX Power Limit field is the amount of dBm EIRP that transmissions on the specified channel should use. If the autoscale bit is set, then the transmission power will be the value, or less (depending on Autoscale algorithm). If autoscale is disabled, then the TX power will be set to exactly the value in the field (or as close as possible).

Channel TX Power Limit Bitfield
Bitfield Position Description
Use Autoscale b7 Set to enable autoscaling for TX (from Channel Parameters field)
TX dBm EIRP value b6:0 Encoded as Value = 2([TX Max dBm] + 40)

Some Examples:
0 dBm TX no autoscale = 80 (0x50)
-15 dBm TX no autoscale = 50 (0x32)
-15 dBm TX with autoscale = 178 (0xB2)

RSSI Limit Bitfield

The Link Quality Filter Level, CS RSSI Level, and CCA RSSI Level fields all have the same data element bitfield. It corresponds to a dBm threshold for RX. In the case of Carrier Sense (CS) and Link Quality Filter, if the RSSI is less than the supplied value, the process fails (CS is a PHY process, Link budget filtering is a DLL/MAC process). In the case of Clear Channel Assessment (CCA, a PHY process), if the RSSI is greater than the supplied value, the process fails. The autoscale feature is not currently applicable for RSSI, and its usage is currently proprietary only.

RSSI Limit Bitfield
Bitfield Position Description
Use Autoscale b7 Set to enable RX autoscaling
RX Limit dBm value b6:0 Encoded as Value = [RSSI dBm] + 140

Regulatory Code

Different regulatory regimes (e.g. FCC 15.231, ERC 70-03) can be applied to a channel. The implementation is required to make the necessary provisions to set output power and/or duty cycles such that the specified regime is not violated during usage. For “closed-loop” applications, this setting can be safely ignored as long as the channel specifications are regulatory compliant for the regimes they are being used in. For devices that might travel from location to location, or be shipped anywhere, a network administrator can write to this field to make sure devices that come into its network abide by the regulatory regime of the network.

Regulatory Code field
Code Description
0x00 Ignore (no limitations)
0x01 Apply TX Duty Cycle Field
0x10 Use ETSI ERC 70-03
0x20 Use FCC 15.231 (a-e)
0x21
0x22
0x23
0x24
All non-listed codes are RFU

Real Time Scheduler (ISF 03)

DASH7 Mode 2 devices may implement a constantly-running Real Time Clock (RTC) to schedule active scan wake-on events as well as beacon events. The scheduling configuration of these events is managed through the Real Time Scheduler ISFB file.

The Sync Mask and Sync Value elements align with the lower half of the 32 bit RTC value (UTC format), allowing a scheduling resolution of one second (1s) and a maximum scheduling period of roughly 18.2 hours. When the lower 16 bits of the RTC value are logically AND’ed with the Sync Mask and the result equals the the Sync Value, a corresponding scheduled event shall commence.

Default Permissions
root: rw- / user: rw- / guest: r–

Length: 12 bytes
Allocation: 12 bytes

Data Element Bytes Offset Description
Sleep Scan Sync Mask 2 0 16 bit mask for Sleep Scan Scheduling
Sleep Scan Sync Value 2 2 16 bit compare value for Sleep Scan Scheduling
Hold Scan Sync Mask 2 4 16 bit mask for Hold Scan Scheduling
Hold Scan Sync Value 2 6 16 bit compare value for Hold Scan Scheduling
Beacon TX Sync Mask 2 8 16 bit mask for Beacon TX Scheduling
Beacon TX Sync Value 2 10 16 bit compare value for Beacon TX Scheduling

Usage: Timing Resolution

Each of the three idle-time processes in DASH7 – Sleep, Hold, and Beacon – can be individually synchronized against an RTC. This allows relatively high-precision TDMA applications to be implemented using DASH7. The minimum resolution is 1 second, which may seem large, but this is just the resolution for synchronization. The synchronization interval (1s to 65535s) are subdivided with the Scan and/or Beacon Series (these are described in the next sections). The slot resolution, therefore, is 1 tick = 1/1024s (0.977ms), but slot series are aligned against a 1s resolution scheduler.

Usage: Setting the Timing Window

Timing Window Resets/Restarts when: (RTC & Sync Mask) = (Sync Value)
For this usage example, the Hold Scan will be used. Assume the device being implemented is a Subcontroller, which by specification will never go into the Sleep State.

Example 1: Synchronize/Restart Hold Scan on 3's, each 16 seconds
Hold Scan Sync Mask: 0x000F
Hold Scan Sync Value: 0x0003

Example 2: Synchronize/Restart Hold Scan at 13's and 15's, each 16 seconds
Hold Scan Sync Mask: 0x000D
Hold Scan Sync Value: 0x000D

As you can see, the Mask-Value method can allow some sophisticated and interesting ways to plan synchronous windows. In typical usage, only a simple, constant window is used, but creative system integrators have the freedom to do much more. By configuration of the Scheduler and Scan/Beacon Series files, many different types of MAC behavior can be achieved. Network administrators have the ability to fundamentally change the MAC of any DASH7 device, in order to dynamically meet the needs of the network, with a simple file data alteration.

Illustrated Scheduling Windows

To be completed

Scan & Beacon Series (ISF 04, 05, 06)

The Scan and Beacon Series are quite similar in function. There is a Sleep Scan Series (ISF 04), a Hold Scan Series (ISF 05), and a Beacon TX Series (ISF 06). The Sleep Scan is used only by Endpoint class devices, since only Endpoint devices go into the sleep state.

Basic Structure of Series Data Elements

The series are stored in files, and contain zero or more scan/beacon elements (if zero, then nothing will happen). The resulting file contents will look something like below. Each file can be up to 256 bytes in length, thus allowing a scan series to contain as many as 64 scan operations, and allowing a beacon series to contain up to 32 beacon operations. After the device gets to the end of the series, it will repeat the series from the beginning. Thus, by defining the scan/beacon series, system integrators are defining the duty cycles and time slot pattern of the DLL/MAC.

Scan 1 Scan 2 Scan 3 Scan N
Scan 1 Params Scan 2 Params Scan 3 Params Scan N Params
Beacon 1 Beacon 2 Beacon 3 Beacon N
Beacon 1 Params Beacon 2 Params Beacon 3 Params Beacon N Params

Each Scan/Beacon element contains some parameters. These parameters can be identified as three types:

  • Channel to use for scan/beacon
  • Scan/Beacon window interval (i.e. “Next Scan” and “Next Beacon”)
  • Control values

DLL/MAC Management of Series Data

The control values are specific to beacons and scans, because these two activities are different. But as DLL/MAC processes they are basically the same, because they both need to use a channel and they both have a duty cycle (window interval). The window interval is front-chained. That is, the next scan/beacon will occur X ticks after the present scan/beacon begins. So, if the scan/beacon process itself takes more time to run than the value of the window interval, then the next scan beacon will happen immediately after the present scan/beacon completes (duty cycle = 100%). It is a “best practice” to always have the window interval longer than the scan/beacon process (in order to maintain some degree of synchronicity during idle time processes) although it is not a requirement. Sometimes, interesting features can arise from using the scan/beacon timing parameters in clever ways.

Finally, the DASH7 Data Link Layer will manage scanning and beaconing in parallel during idle time. The event priority is shown below.

  1. Active RX/TX of over-the-air packets
  2. Scanning
  3. Beaconing

Therefore, if a scan event occurs during an active RX/TX, it will be postponed. If a beacon event occurs during active RX/TX or during the active part of a scan, it will be postponed until the device is once again idle. System integrators who seek to implement highly synchronous networks (e.g. TDMA) should set the scan/beacon parameters to minimize or eliminate this kind of event collision.

Channel Scan Series File

An ordered list of Scan Series data: when the device begins its scan, the first datum of the list will be monitored for evidence of channel traffic. If none is detected within the scan timeout, the device shall wait until for a period of time (next scan) before repeating the process on the next datum of the list. If a datum includes an unsupported Channel ID, its scan shall be processed as unsuccessful.

Default Permissions
root: rw- / user: rw- / guest: r–

Length: 4 Bytes per channel scan datum
Allocation: Minimum 32 bytes

Scan Series Format
Data Element Bytes Offset Description
Channel ID 1 0 Transport Channel ID (see PHY) for scan
Scan Code 1 1 Contains scan type flag, and an EXP+MANT encoded scan timeout value
Next Scan 2 2 Integer number of ticks (1/1024s) between start of present scan and start of next scan
Scan Code Field
Bitfield Position Description
Scan Type b7 0 uses Foreground Scan, 1 uses Background Scan
Scan Timeout EXP b6:4 Timeout (ticks) = (4'EXP)(MANT+k); k=0 when EXP=0, k=1 when EXP>0
Scan Timeout MANT b3:0

In this data element structure, the “window interval” described earlier in the section is determined by the value of “Next Scan.” The “Scan Timeout” value determines the duration of time where the radio is actively listening for some data on the channel (i.e. RX mode active, searching for sync word). If the Scan Type value is set, there is also a stipulation that carrier sense detection must be valid.

So, for these “background scans” (see DLL), the active scanning will terminate under any of the conditions below:

  1. Carrier Sense is not detected within threshold set in the selected channel's Channel Configuration Element (ISF 02)
  2. Scan Timeout occurs
  3. Sync word is detected, and a packet begins RX (success)

For “foreground scans” there is no requirement for carrier sense detection.

Beacon Scan Series File

Identical in concept to the Channel Scan Series but for sending Beacons (if enabled). Beacons are automated transmissions of the Broadcast Announcement Command. If the Beacon is specified incorrectly (invalid Channel ID, Command Code, or Data Return ID), the Beacon shall be processed as unsuccessful, and it shall not be transmitted.

Default Permissions
root: rw- / user: rw- / guest: r–

Length: 8 Bytes per Beacon datum
Allocation: Minimum 24 bytes

Beacon Series Format
Data Element Bytes Offset Description
Channel ID 1 0 Transport Channel ID (see PHY) for scan
Command Params 1 1 Bitfield parameters that map to Data Link Layer and M2QP command request parameters
M2QP Call Template 4 2 Single File or File Series Call Template, padded to 4 bytes (see M2QP)
Next Beacon 2 6 Integer number of ticks (1/1024s) between start of present beacon and start of next beacon
Beacon Command Params Field
Bitfield Position Description
VID b5 Set to use VID in beacon packet instead of UID
NLS b4 Set to use Network Layer Security on the Beacon packet
No CSMA b2 Force beacon TX to bypass CSMA
No Resp b1 Set No Resp bit to prevent recipients from attempting responses
F/S b0 Set/Clear to use File-Series/Single-File call template in M2QP Call Template field

To give more information about the F/S bitfield, it informs the beacon process whether to form a beacon using the Announcement from File or Announcement from Series M2QP command formats. Each of these commands uses the M2QP call template in a slightly different way.

Some Examples Showing Device-Class Manipulation

In some cases, just by changing the active device-class (Endpoint, Subcontroller, Gateway) can be sufficient for deploying multi-mode devices that have runtime selectable modes. The supported device classes are contained in the Device Features file (ISF 01) and the active device class is defined in the Network Settings file (ISF 00). To change the active mode, firmware running on the device should change the value of the active device class in the Network Settings file, or alternatively a user with appropriate permissions to write to the Network Settings file can make the same change over the DASH7 air interface.

Endpoint to Subcontroller

To be completed

  • Show Sleep Scan and Hold Scan alternation in Endpoint
  • Show Hold Scan in Subcontroller
  • Show how device switches

Endpoint to Gateway

The distinction between Subcontroller and Gateway device classes has nothing to do with the DASH7 lower layers (PHY, DLL, Network, Transport) which treat the two device classes identically. It is instead a distinction about required features of the application layer. Therefore, when changing from Endpoint to Gateway, the result is exactly the same as changing from Endpoint to Subcontroller. Likewise, changing from Subcontroller to Gateway is imperceptible to the lower layers (but it may have impact on way the application works).

Some Examples Combining Scheduling with Scan Series

Here is a special section showing how, by manipulation of ISF 03, 05, and 06, a Subcontroller class device can be modified to take-on all different sorts of behavior. Endpoint class devices could be configured similarly, considering ISF 03, 04, and 05.

Scheduled Hold Scan Series

To be completed

  • Show Time slotting of Scan series
  • Show event generation from Scheduler
  • Show how scan series is reset on scheduler event
  • Show how scheduling can deal with asynchronous communication.

Scheduled Beacon Series

To be completed

Scheduled Scanning and Beaconing

To be completed

  • Show that scan and beacon scheduling can overlap, or be the same event
  • Show that Scanning takes priority over beaconing

TDMA, Guaranteed Time Slots, and 802.15.4 Superframe Implementation

To be completed: basically just a wrap-up, describing how “Scheduled Scanning and Beaconing” may implement all manners of complex TDMA and mixed-mode MACs, even 802.15.4.

dash7_mode_2/registry_guide.txt · Last modified: 2012/04/19 19:09 by jpnorair