Wi-SUN Network Topology Management

In a typical Wi-SUN FAN network deployment, the nodes are allowed to join the border router’s network and the most optimal network is formed automatically. But in certain use-cases (typically in a test scenario) where the user wants to control the topology of the deployed network, the user can leverage the features provided in TI Wi-SUN FAN stack examples to form a network of required topology.

Note

During deployment of a Wi-SUN network, it is recommended to allow the nodes to form the Wi-SUN network on their own without any filter lists, so that they form the most optimal network.

There are three features that allow the user to control the network topology. Two of them (MAC filterlist, PAN ID list) are Wi-SUN FAN compliant and are described in this section.

Warning

The Join to Specific Border Router/EUI based Controlled Device Joining feature also allows topology control but is not Wi-SUN compliant and is described under Advanced TI Wi-SUN FAN Stack Features section.

MAC filterlist

MAC filtering can be used to force Wi-SUN nodes to communicate with other Wi-SUN nodes of specific MAC addresses. By limiting the potential neighbours of a node, you can force hops in a small network and test your application when there are hops in the network. This allows you to perform tests on how the number of hops, affect your application.

This feature can be used in the ns_br (border router) and ns_node (router node) projects through pyspinel. Pyspinel help command will provide an example usage.

../_images/helpmacfilterlist.png

Figure 32. Pyspinel help for macfilterlist

To get the MAC address of the device, you can use UniFlash. Under Settings and Utilities, it is the primary IEEE address. While using the address in the macfilter APIs, remove the ‘:’ damarcators from the address.

../_images/mac_address_uniflash.PNG

Figure 33. Mac Address of device on UniFlash

Alternatively, you can use the hwaddress API on pyspinel to get the MAC address of the device.

../_images/mac_address_pyspinel.PNG

Figure 34. Mac Address of device on PySpinel

An example use-case of the MAC filterlist is depicted below.

The following network topology is enforced by strategically allowing the nodes to communicate to only specific neighbours.

Consider the border router (BR) and router nodes (RN) A, B and C. We can force a topology where node C joins the network through node B, which in turn joins through node A. The following image depicts the achieved topology with the MAC filter applied on the devices.

../_images/macfilterlist.png

Figure 35. Forcing hops using Macfilterlist feature

The border router has only router node A in its allow list. This allows border router to talk only with router node A. Router node A can talk to the border router and RN B.RN B is allowed to communicate with RN A and RN C. And RN C can only communicate with RN B.

This forces all the communication between border router and router node C to pass through router node B and A.

Some things to note when using the mac filter list feature:

  1. The macfilter lists must be applied before the interface and stack is brought up. This means that macfilter lists must be updated before interface up and wisunstack start is called on pyspinel.

  2. Mac filter lists get erased on a reset and must be applied again before the stack is brought up.

  3. Each node has its own MAC filter list. This is not something that is maintained at the border router.

PAN ID allow/deny list

PAN ID allow/deny list is a list of network PAN IDs that a coap node is allowed to join or blocked from joining. Each coap node has its allow list/deny list. In a deployment scenario where you want specific router nodes to join the network (PAN) of a specific border router, then you can use the PAN ID allow/deny list feature.

Note

PAN ID allow/deny list only works with the CoAP node example. You need to build the projects with COAP_PANID_LIST predefine to use this functionality. Pyspinel is used on the host side to update the allow/deny lists. The feature is implemented in the application layer. The decision to allow/deny a node happens once the node joins the network. If the node is allowed to stay, there is no effect. If the node is not allowed, it triggers a rediscover and the node searches for a new PAN.

There are two approaches to make use of this feature. The first approach is to maintain a JSON file with the MAC addresses of the coap nodes and its corresponding allow/deny lists. This JSON file is supplied to the border router through setpanidlistjson API on pyspinel.

When a new coap node built with the predefined symbol COAP_PANID_LIST, joins the network, the border router looks up the MAC address of the joined node in the supplied list in the json file. If the address of the node exists, it sends the allow/deny list of the node as a CoAP packet and the node updates its allow/deny lists. Then the node checks if the panid of the current network it has joined, is on the allow list or not. If it is not, then it triggers a rediscover.

@startuml participant "CoAP Node" participant "Border Router" group CoAP Node joins Border Router PAN end "CoAP Node" -> "Border Router" : Request PAN ID allow/list from Border Router rnote over "Border Router" Look up MAC address of joined node in json file and retrieve the PAN ID list of joined node end note "CoAP Node" <-- "Border Router" : PAN ID allow/deny list from Border Router to CoAP Node rnote over "CoAP Node" Update its PAN ID lists and Check if PAN ID of current network is in allow list end note "CoAP Node" -> "Border Router" : Notify Border Router that rediscover is not necessary @enduml

Figure 36. Join process when PAN ID is in allow list of node

@startuml participant "CoAP Node" participant "Border Router (BR)" group CoAP Node joins Border Router PAN end "CoAP Node" -> "Border Router (BR)" : Request PAN ID allow/deny list from BR rnote over "Border Router (BR)" Look up MAC address of joined node in json file and retrieve the corresponding PAN ID list of joined node end note "CoAP Node" <-- "Border Router (BR)" : PAN ID allow/deny list from BR to CoAP Node rnote over "CoAP Node" Update its PAN ID lists and check if PAN ID of current network is in allow list of the node end note "CoAP Node" -> "Border Router (BR)" : Notify BR that rediscover is necessary "CoAP Node" -> "CoAP Node" : Trigger PAN rediscover rnote over "CoAP Node" Look for new PANs and restart join process with a new BR end note @enduml

Figure 37. Join process when PAN ID is in deny list of node

The second approach is useful if you haven’t maintained a JSON file with allow/deny lists. You can update the PAN ID allow/deny lists of a specific node with setpanidlist API on pyspinel.You can retrieve the PAN ID lists from the nodes with the getpanidlist` API and trigger a PAN rediscover of the node through panrediscover API. Please refer to pyspinel help for example usage of these APIs.