[RFC] net: l2: ieee802154: TSCH protocol support

Why TSCH protocol support?

The IEEE 802.15.4e amendment introduced the Time Slotted Channel Hopping (TSCH) protocol to the standard. This was later consolidated into IEEE802.15.4-2015 and all following versions of the standard. Wikipedia has a quick introduction.

TSCH in IEEE 802.15.4 is designed around very similar concepts as the WirelessHART standard which is widely adopted in industrial applications. In fact both standards compete directly and have repeatedly inspired each other. TSCH combines very low packet rejection rates and real-time capabilities with excellent low-energy properties. It can be used in star and mesh topologies.

A dedicated IETF working group has defined a range of higher-level standards and profiles (6TSCH) on top of the protocol. Namely IPv6 over TSCH as well as an adaptation of the RPL routing protocol (among others). This defines a full network stack on top of TSCH which is equally well suited to large-scale IoT-applications as the more traditional non-beacon-enabled/6LoWPAN stack underlying Thread/ZigBee.

These two alternatives are however not to be regarded as being interchangeable. TSCH is optimized for harsh industrial environments with high reliability and deterministic timing requirements while the Thread/ZigBee protocols are more focused onto the office/home-automation market. TSCH might therefore increase Zephyr's attractiveness to industrial automation and medical use cases.

Implementation

This feature request is not new to Zephyr, it revives parts of #3710, namely #2399 which again requires #2397, #2392 and parts of #2398.

A detailed implementation plan follows below which can be transformed into individual issues and implemented step-by-step (iteratively) once the principle as such has been agreed.

Alternatives

Thread/Zigbee/WiSUN or even raw IEEE 802.15.4 might be regarded as alternatives. But these are to be seen as complementary protocols with different focus, strengths and weaknesses. Namely the superior approach to collision avoidance (deterministic latency) and channel hopping (reliability, resistance to interference) in TSCH as well as highly configurable throughput and latency per device (QoS) are strengths of the TSCH protocol while it is weaker when it comes to ease of configuration, deployment, administration and usage (which makes it less adequate in a home/office automation setting).

Solution Design

A premliminary analysis of the specification (IEEE 802.15.4-2015 or -2020) yielded the following tasks that might be implemented roughly in the order given below:

• Improve short address support in the IEEE 802.15.4 stack as a precondition for TSCH link tables (currently short addresses are not fully supported) - may require a neighbor table (done, see net: l2: ieee802154: improved/fixed endianness and short address handling #50400)
• Consolidate IEEE802.15.4 options in net_pkt:
  • Consolidate all pre-existing IEEE 802.15.4-specific fields in net_pkt into a separate struct ieee802154_attr (or similar) pointed to from net_pkt and only allocated/assigned for packages directed to IEEE 802.15.4 interfaces. (Note: The current approach breaks net stack encapsulation, does not scale well and has increasingly negative memory usage effects when non-IEEE 802.15.4 interfaces are used in parallel with IEEE 802.15.4 interfaces.) (done, see Refactor/consolidate net pkt ieee802154 options #51266)
• Support for enhanced beacons and ACKs with TSCH specific IEs:
  • Extension of the frame data model (structs, enums)
    • Implement Header IEs (7.4.2)
      • 7.4.2.7 Time Correction IE
      • 7.4.2.17 Header Termination 1 IE
    • Implement MLME Payload IE (7.4.3) with Nested IEs (7.4.4)
      • 7.4.4.2 TSCH Synchronization IE
      • 7.4.4.3 TSCH Slotframe and Link IE
      • 7.4.4.4 TSCH Timeslot IE
      • 7.4.4.31 Channel hopping IE
  • RX Support - Parsing and handling of enhanced beacons and ACKs in ieee802154_recv(), ieee802154_handle_beacon() (i.e. MLME-BEACON-NOTIFY.indication primitive for enhanced beacons) and handle_ack().
  • TX Support - Creating and sending of enhanced beacons (i.e. MLME-BEACON.request/confirm primitive for enhanced beacons) and enhanced ACKs.
• MAC PIB extensions
  • 8.4.2.1 General MAC PIB attributes for functional organization
  • 8.4.2.2 TSCH-specific MAC PIB attributes
  • 8.4.2.3 MAC PIB attributes for hopping sequence
• Consolidate MAC configuration
  • Extend the IEEE 802.15.4 network management API to allow for generic configuration of additional MAC PIB attributes.
  • MLME-GET.request/confirm
  • MLME_SET.request/confirm
  • MLME-RESET.request
• Implement required MLME extensions in the network management API
  • MLME-SET-SLOTFRAME.request/confirm
  • MLME-SET-LINK.request/confirm
  • MLME-KEEP-ALIVE.request/confirm
• Implement required MLME extensions in KConfig
  • MLME-TSCH-MODE.request/confirm (implies support for FFD/co-ordinator role to start a TSCH)
  • Memory limits for slotframes, links and channel hopping sequences
  • Selection of compile-time MAC PIB options (e.g. TSCH-CCA-mode, implicit broadcast)
• Extend the IEEE 802.15.4 driver API with a get_attr() method as proposed in Add support to transport IEEE 802.15.4 PPDU + Padding between drivers instances and L2 - MAC #49775 . This would also enable proper headspace and FCS handling as proposed there by letting drivers communicate their headspace requirements and FCS handling approach to L2.
• Neighbour Table
  • Optional: Short address support for IEEE 802.15.4 security
  • Structures to support per-neighbour TSCH link config and frame scheduling
• Implement TSCH PAN/Slotframe operation based on the Contiki-NG implementation which is well tested and can be largely re-used and adapted to Zephyr.
  • 6.2.6 TSCH slotframe structure
  • 6.2.10 Channel hopping
  • 6.3.6 TSCH PAN formation
  • 6.4.2 Additional disassociation behavior
  • 6.5.4 Synchronization in TSCH PAN
  • 6.7.1 Transmission: only one frame per slot if security is enabled
  • 6.7.4.2 Acknowledgment
  • 6.7.4.3 Retransmissions: deviating security procedure based on ASN
  • 6.7.5/6 Transmission timing restrictions, guard time
  • 7.2.1.3 Frame Pending field: extra behavior
  • Chapter 9. Security: deviating behavior
  • TSCH-specific CCA/CSMA:
    • 6.2.5.1 Overview
    • 6.2.5.2 TSCH CCA
    • 6.2.5.3 TSCH CSMA
  • Implementing timing should mostly be possible with the existing radio API. It is however probably that some minor changes to the API are required to support all features.
• Optional: Replace/deprecate CONFIG_IEEE802154_2015 (w/o breaking backwards compat):
  • Better represent what this flag actually does. This flag is not meant to cover all -2015 features, it rather covers some very specific features (namely HW security, CSL) which should be named explicitly.
  • Introduce a scalable configuration pattern (based on devicetree, Kconfig, net_mgmt - depending on the context) that can be extended to all -2015+ features and avoid further pollution of the configuration namespace by overly generic flags.
  • Improve spec conformity of the IEEE 802.15.4-specific net_pkt content (e.g. wrt IEEE 802.15.4 frame version, ACK info, etc.).
• Optional: MAC data service extensions (MCPS-SAP, later on partly accessible via userland socket parameters) via the newly introduced net_pkt->ieee802154_attr, enabled by Kconfig feature switches.
  • MCPS-DATA.request: NestedIeSubIdList, AckTx, SecurityLevel, KeyIdMode, KeySource, KeyIndex plus optionally HeaderIeList and PayloadIeList which are not strictly required for TSCH
  • MCPS-DATA.confirm: Timestamp, PayloadIeList, AckPayload plus optionally HeaderIeList, NumBackoffs, return value: Status
  • MCPS-DATA.indication: PayloadIeList, MpduLinkQuality, Timestamp, SecurityLevel, KeyIdMode, KeySource, KeyIndex plus optionally HeaderIeList, Dsn
• Optional: Socket extension
  • Introduce AF_IEEE802154 specific sockets (additionally to the already introduced RAW/DGRAM versions) which allow binding, connection, socket options, etc. along the same line as Linux's AF_IEEE802154 socket.
  • Extend & use socket_nm messages to configure L2 for TSCH, see https://elixir.bootlin.com/linux/latest/source/net/ieee802154/netlink.c#L84, https://elixir.bootlin.com/linux/latest/source/include/linux/nl802154.h#L11
  • Optional: Introduce SOL_IEEE802154 socket option level: initially WPAN_WANTACK, WPAN_WANTLQI, WPAN_SECURITY, WPAN_SECURITY_LEVEL, see https://elixir.bootlin.com/linux/latest/source/net/ieee802154/socket.c#L873 plus additional TSCH-specific options.

UML

TSCH operation

IE Parser

@rlubos @jukkar @nandojve As always I'm trying to implement this in my free time so I prefer an iterative approach that leaves the code base in a clean and generally improved state even if I have to stop in the middle due to lack of time.

In that sense I'd like to start with two preparatory tasks:

• Improve short address support in the IEEE 802.15.4 stack as a precondition for TSCH link tables (currently short addresses are not fully supported) - may require a neighbor table
• Consolidate IEEE802.15.4 options in net_pkt (see detailed approach and rationale above)

What do yo think of this, do you agree that these two changes introduce value as such? If so I'd start by providing individual PRs for those two issues first. I'd just like a quick thumbs up from your side, especially before changing the (internal) structure of net_pkt to improve its memory footprint/maintainability/encapsulation.

@nandojve : As you can see in the above todo list I also intend to work towards the improvements discussed in #49775 - these come at a later stage, though, where they fit better what is actually needed to proceed.

[rlubos]

Thanks @fgrandel, I agree that the two initial tasks proposed by you sound like valuable additions. Adding OT guys on the CC, since the OpenThead is currently the main target of the 15.4-specific net_pkt fields. CC @edmont @lmaciejonczyk @canisLupus1313

As for get_config() - there were some discussions in the past regarding adding such an radio API function, here's the link for some background (#23347 (comment)). Personally though, I have no problem for such an API extension.

@rlubos Thanks for your quick response. I'm going to work on those first steps then.

Taking up the ball re configuration getter to propose something more specific:

Do we need a generic getter in the radio API at all?

@tbursztyka 's argument against a generic configuration getter in #23347 was based on the assumption that L2 owns all configuration logic required in L2. While this is true for writable configuration it is not for read-only attributes of the driver:

• In Add support to transport IEEE 802.15.4 PPDU + Padding between drivers instances and L2 - MAC #49775 we've identified some driver-specific attributes which must be available in a generic way in L2 (read only!). Namely the hardware-specific headroom to be reserved in the frame buffer for zero-copy/DMA support and FCS handling properties of the driver. The latter may be implemented as a HW capability, though.
• There is already a read-only getter in the driver API for an attribute that does not change at runtime (get_subg_channel_count()).
• CONFIG_IEEE802154_2015 enables a rather eclectic and non-systematic collection of (partial) features from the spec and implies certain boolean capabilities as well as non-boolean attributes.
• I can imagine other read-only, non-boolean driver properties which may in the long run be relevant (e.g. supported channel pages, supported PHYs, a few read-only PIB attributes from the spec, properties influenced by driver-specific Kconfig/DT props, etc.).

Injecting driver properties as "capabilities" into L2 does not scale for non-boolean attributes and makes it too easy to violate the spec. A good example is IEEE802154_HW_2_4_GHZ and IEEE802154_HW_SUB_GHZ plus get_subg_channel_count(). This is clearly against the spec's much more flexible concept of integer-valued channel pages which uniquely determine the number and frequency bands of available channels. Adding a new getter for every driver attribute in the future doesn't scale well either.

The same is true for global Kconfig constants and direct access to DT driver props from L2. The much too broadly defined CONFIG_IEEE802154_2015 is a good example. It actually represents a mixture of (non-boolean and boolean) attributes/capabilities as well as parameters that should be configurable at runtime according to the spec (whether or not to use CSL for example). It's also not a good idea to tie features to a specific version of the spec. Should this constant now be renamed to _2020? ;-)

Having a generic getter for read-only attributes let's us model the API closer to the spec's flexible and future-proof PHY PIB concept.

What could be included in the generic getter?

Possible attributes to be served by a generic getter:

1. implementation-specific (non-PIB) read-only attributes that do not change at runtime and cannot be conceptualized as "capabilities", e.g. required buffer headspace.
2. read-only PIB attributes which do not change at runtime (not yet required).
3. valid ranges for writable configuration attributes, e.g. available channel pages, which do not change at runtime
4. the current state of attributes configurable via configure() - not recommended
5. internal driver state that changes at runtime (current time, current clock precision, etc.) - not recommended

I tend to follow along the lines of @tbursztyka 's argument to only include such attributes that are not writable by L2 and do not change at runtime (categories 1-3) to keep the changes required in existing driver code to a minimum.

I therefore propose the following minimal changes:

• introduction of a generic getter that can serve attributes of category 1-3 above
• introduction of a "required headroom" attribute (category 1) across all drivers
• refactoring of IEEE802154_HW_2_4_GHZ, IEEE802154_HW_SUB_GHZ and get_subg_channel_count() into an attribute "available channel pages" (category 3) plus a configuration value "currentChannelPage" (PHY PIB attribute phyCurrentPage) across all drivers. The number of available channels must either be derived from the selected channel page (for spec-compliant drivers) or be kept in a separate attribute (iff there are drivers violating the spec).
• moving set_channel() and set_txpower() into the configuration
• implementing the FCS handling property as a HW capability
• deprecating CONFIG_IEEE802154_2015 along the lines of my original proposal into a mixture of writable and read-only driver attributes and/or hardware capabilities (potentially influenced by much more specific Kconfig constants that enable certain features independently of a specific spec version).

The length of the FCS as well as the algorithm required to calculate it (if the driver does not provide the FCS on RX) is a deterministic function of a few well-defined PIB attributes (category 2 or 4). So the above API also enables this requirement from #49775 without implementing it yet.

While the hardware capabilities could become just another "attribute" I'd vote against this, to keep the change small and to maintain similarity with the ethernet driver API.

I'd also not touch get_time() and get_sch_acc() as they are updated at runtime.

How to name the API?

I did a quick search across all driver APIs. Here my result:

• configure()/config_get() is used in uart, i2s, i3c
• config_set()/config_get() is used in dai
• set_config()/get_config() is used in ethernet, virtual
• get_properties() is used in dai
• attr_get() is used in sensor

If we follow @tbursztyka 's recommendation to not introduce a symmetric configuration getter then I propose that we use attr_get():

• this is in line with the spec's "PIB attribute" nomenclature
• anything with "config*" in its name may be mistaken for a symmetric configuration getter by users
• we leave the API namespace open for an additional future symmetric configuration getter that uses the same types as configure() if our assumption that such a thing is not needed turns out to be wrong.

[nandojve]

@nandojve : As you can see in the above todo list I also intend to work towards the improvements discussed in #49775 - these come at a later stage, though, where they fit better what is actually needed to proceed.

Hi @fgrandel ,

It`ll be great have TSCH on Zephyr. Yes, I want to continue look on #49775 as soon new release is launched.

@rlubos @nandojve Now that the initial preparation has been submitted for review and merged I'm concentrating on introducing enhanced beacons and enhanced ACKs. They are the first thing that devices will have to send (TSCH PAN coordinator) and receive (initial synchronization of participating devices) in a TSCH.

If you agree then this iteration will contain sending and parsing of enhanced beacons and ACKs with TSCH in mind, i.e.:

• header IEs (7.4.2):
  • 7.4.2.17 Header Termination 1 IE
• the MLME payload IE (7.4.3) with nested IEs (7.4.4):
  • 7.4.4.2 TSCH Synchronization IE
  • 7.4.4.3 TSCH Slotframe and Link IE
  • 7.4.4.4 TSCH Timeslot IE
  • 7.4.4.31 Channel hopping IE

This iteration introduces generally useful features (handling IEs in the soft-MAC layer) plus advances my personal development agenda.

Now that the initial preparation has been submitted for review and merged I'm concentrating on introducing enhanced beacons and enhanced ACKs.

@rlubos @nandojve I'm slowly making progress towards the next iteration. This step is going to be much larger than the previous ones. I'm developing it in the open in case you'd like to have a sneak preview. Once I got a working state I'm going to cut it into small steps and provide several PRs for it.

[nandojve]

Hi @fgrandel ,

Thank you for update us about this work. I understand this is a huge step inside Zephyr and I would like know what will be the base line that we need follow/compare. I mean:

1- What is the validation approach to make sure it is working properly?
2- How will be the setup environment, guideline?
3- What are the SW/HW involved in this process?

I think it is important we establish how people can put TSCH to work to make easy to test and decrease pressure in the test/regression phase during review.

I imagine that you already have a plan/setup and I was wondering if it is an a phase that can be shared?