Skip to content

API Documentation

Jump to bottom
Samuele Zoppi edited this page Jul 20, 2020 · 3 revisions

Network Manager application in Python

A Network Manager application is implemented in the form of a Python script contiki-ng/os/services/dynsched/python/nm_serial.py

The script spawns two threads:

  1. rthread - Reads incoming data from the serial port, usually logs from the contiki-ng application.
  2. sthread - Prints the Schedule choices, accepts the choice of schedule as user input, formats the schedule object into a string and sends the string to the attached Coordinator node over the serial port.

Schedules are stored in an object of class schedule. Each Schedule object consists of:

  1. num_links parameter which indicates the number of links present in the schedule.
  2. An array link_info_links containing objects of class link_info which contain parameters of links in the schedule.
class link_info:
        def __init__(self, ts, choff, lo, nid):
		self.timeslot = ts
		self.channel_offset = choff
		self.linkopt = lo
		self.nodeid = nid

class schedule:
	def __init__(self, num):
		self.num_links = num
		self.link_info_links = []

The Schedules are populated in the schedulesArray before hand. This is effected by using a 2D array input to the function create_schedule_from_array. sthread displays the available choice of Schedules fetched from schedulesArray and waits for the user to choose one of the choices. Following is the format of Schedule choices

*************************************************
	      Choice of Schedules 	    
Choice 1: 

---------------------------------------------

Number of links: 4
Link 0:  Timeslot:0  Choff:0 Linkopt:1 NodeID:1
Link 1:  Timeslot:1  Choff:0 Linkopt:1 NodeID:2
Link 2:  Timeslot:2  Choff:0 Linkopt:1 NodeID:3
Link 3:  Timeslot:3  Choff:0 Linkopt:1 NodeID:4

---------------------------------------------
.....

*************************************************

Depending on the choice entered, sthread writes the appropriate Schedule over the serial port which is read by the Coordinator. When any key other than a number is entered, both rthread and sthread are stopped and the script terminates.

Formatting Schedules sent over serial port:

The Schedules are stored as a schedule object in the NM application. To make it easier for the Contiki-NG application to parse these Schedules sent over serial port, the NM application formats the schedule object into a string. The function format_schedule_obj() creates a string containing schedule info which is then sent over the serial port. Following is the format of the string

"N<number of links> L<Link number> <timeslot>,<choff>,<linkopt>,<nodeid> L<Link number> <timeslot>,<choff>,<linkopt>,<nodeid> ..."
Eg: "N4 L0 0,0,1,1 L1 1,0,1,3 L2 2,0,1,2 L3 3,0,1,4"

Dynamic Scheduling API

The following structure is used to maintain network schedules to be sent out by the Coordinator. https://github.com/tum-lkn/contiki-ng/blob/f7b63e388f1fb0e1f0fc84a0f3cbd445579ea2c1/os/services/dynsched/infra/dyn_sched.h#L53

struct network_schedules {
  uint8_t num_links;
  struct tsch_slotframe_and_links_link links[FRAME802154E_IE_MAX_LINKS];
};

The structure tsch_slotframe_and_links_link is modified to contain the nodeid field. https://github.com/tum-lkn/contiki-ng/blob/f7b63e388f1fb0e1f0fc84a0f3cbd445579ea2c1/os/net/mac/framer/frame802154e-ie.h#L55

struct tsch_slotframe_and_links_link {
  uint16_t timeslot;
  uint16_t channel_offset;
  uint8_t link_options;
  uint8_t nodeid;
};

dynsched_update_network_schedules() is used to update the network_schedules struct. The function takes the link properties input as a 2D array of the following format.

| timeslot | channel offset | link_options | node ID |
| timeslot | channel offset | link_options | node ID |
.
.
N Links

tsch_packet_create_eb() at the Coordinator picks up the schedule and populates it in the EB's Information Element (IE) using the function dynsched_create_ies_sf_and_link().

eb_input() at the Nodes parse the EB, use the IE contained in the EB and create their schedule accordingly using dynsched_create_schedule_from_ies().

Schedule population at the Node:

Each Node parses the EB and extracts the dynsched_schedules information from it. After doing so, it only adds those links in which nodeid field matches self node id. The rest of the links in the slotframe are configured to be LINK_OPTION_RX.

Linktype:

Coordinator is configured with LINK_TYPE_ADVERTISING whereas the Nodes are configured with LINK_TYPE_NORMAL. This is to stop the Nodes from sending EBs.

Dynamic Scheduling operation with Network Manager

  1. Run the Python Network Manager(NM) script.
  2. The script prints out the choices of Schedules out which one choice has to be selected.
  3. The selected schedule is sent to the Coordinator over the serial interface.
  4. The NullNet application running at the Coordinator receives the schedule over the serial interface and calls dynsched_update_network_schedules() to populate the struct network_schedules with the received Schedule.
  5. While creating EB packet, Coordinator includes the data contained in network_schedules as part of the IE present in the EB packet.
  6. When the EB packed is received at the Node, it parses the IE contained in the EB and populates its Schedule.
  7. The information contained in the EB is the same for all Nodes. The Node identifies the relevant link to be populated using the nodeid field.
  8. The NM script always waits for user input at Step no. 2. Once a choice is entered, the selected schedule is sent to the Coordinator and further steps take place.

Flow Diagram of Dynamic Scheduling infrastructure

Critical aspects of the implementation

  1. While including the Schedule in the EB, only slotframe is fetched from Coordinators schedule whereas rest of the info is fetched from the dynsched_schedules struct which is independent of Coordinators Schedule.

  2. At the Node, while adding a link, an RX link is added by default. Only if the nodeid field in the IE matches that of the Node, then a link with corresponding link_options will be added.

  3. Both at the Coordinator and Node, it is observed that a certain number of slots are skipped every time the Schedule is changed. (Scope for evaluation).

  4. Due to high traffic on serial ports, sometimes invalid strings are sent over the serial port. Appropriate checks have been put in place to discard such half-cooked strings.

  5. Changing tx slots of coordinator in adjacent schedules might cause nodes to miss EBs. Nodes might be in TX at that time slot as per the old schedule and hence cannot listen to the new EB sent by the Coordinator as per new Schedule.

  6. It is advised to have a fixed TX slot for the Coordinator for the entire network period where all the other Nodes are in RX. This will make sure that the Nodes won't miss the Coordinator's EBs at any point.

Scaling:

The determining factor for the scaling of the implementation is the size of the network schedule that can be incorporated in an EB. Currently, it is limited by the parameter FRAME802154E_IE_MAX_LINKS given by 4. This decides the number of links that can be embedded in the IE of the EB. Higher the value, morennumber of links can be embedded in the EB and hence larger network schedules can be communicated to accommodate more number of Nodes. The following parameter from the dynamic scheduling APIs maps on to the above mentioned MAX_LINKS parameter DYNSCHED_TSCH_SCHEDULE_DEFAULT_LENGTH. It is observed that the dynamic scheduling network can be sustained up until the value of 14. After which the header size of 802.15.4 frame exceeds the limit and EB packet creation fails in the function create_frame(). So, with the current implementation, the network can be scaled up to 14 Nodes. https://github.com/tum-lkn/contiki-ng/blob/f7b63e388f1fb0e1f0fc84a0f3cbd445579ea2c1/os/net/mac/framer/framer-802154.c#L60

Clone this wiki locally