The IEEE 802.15.4-2015 TimeSlotted Channel Hopping (TSCH) protocol. More...

Files
file	tsch-adaptive-timesync.h
	TSCH adaptive time synchronization.

file	tsch-asn.h
	TSCH 5-Byte Absolute Slot Number (ASN) management.

file	tsch-conf.h
	TSCH configuration.

file	tsch-const.h
	TSCH constants.

file	tsch-log.h
	TSCH per-slot logging.

file	tsch-packet.h
	TSCH packet parsing and creation.

file	tsch-queue.h
	TSCH queues.

file	tsch-rpl.h
	TSCH-RPL interaction.

file	tsch-schedule.h
	TSCH scheduling engine.

file	tsch-security.h
	TSCH security.

file	tsch-slot-operation.h
	TSCH runtime operation within timeslots.

file	tsch-types.h
	TSCH types.

file	tsch.h
	Main API declarations for TSCH.

Data Structures
struct	tsch_asn_t
	The ASN is an absolute slot number over 5 bytes. More...

struct	tsch_asn_divisor_t
	For quick modulo operation on ASN. More...

struct	tsch_log_t
	Structure for a log. More...

struct	tsch_link
	An IEEE 802.15.4-2015 TSCH link (also called cell or slot) More...

struct	tsch_slotframe
	802.15.4e slotframe (contains links) More...

struct	tsch_packet
	TSCH packet information. More...

struct	tsch_neighbor
	TSCH neighbor information. More...

struct	input_packet
	Stores data about an incoming packet. More...

Macros
#define	TSCH_ASN_INIT(asn, ms1b_, ls4b_)
	Initialize ASN.

#define	TSCH_ASN_INC(asn, inc)
	Increment an ASN by inc (32 bits)

#define	TSCH_ASN_DEC(asn, dec)
	Decrement an ASN by inc (32 bits)

#define	TSCH_ASN_DIFF(asn1, asn2) ((asn1).ls4b - (asn2).ls4b)
	Returns the 32-bit diff between asn1 and asn2.

#define	TSCH_ASN_DIVISOR_INIT(div, val_)
	Initialize a struct asn_divisor_t.

#define	TSCH_ASN_MOD(asn, div)
	Returns the result (16 bits) of a modulo operation on ASN, with divisor being a struct asn_divisor_t.

#define	TSCH_LOG_ADD(log_type, init_code)
	Use this macro to add a log to the queue (will be printed out later, after leaving interrupt context)

Typedefs
typedef rtimer_clock_t	tsch_timeslot_timing_ticks[tsch_ts_elements_count]
	TSCH timeslot timing elements in rtimer ticks.

typedef uint16_t	tsch_timeslot_timing_usec[tsch_ts_elements_count]
	TSCH timeslot timing elements in micro-seconds.

Enumerations
enum	link_type
	802.15.4e link types. More...

enum	tsch_timeslot_timing_elements
	TSCH timeslot timing elements. More...

Functions
void	tsch_timesync_update (struct tsch_neighbor *n, uint16_t time_delta_asn, int32_t drift_correction)
	Updates timesync information for a given neighbor. More...

int32_t	tsch_timesync_adaptive_compensate (rtimer_clock_t delta_ticks)
	Computes time compensation for a given point in the future. More...

void	tsch_adaptive_timesync_reset (void)
	Reset the status of the module.

long int	tsch_adaptive_timesync_get_drift_ppm (void)
	Gives the estimated clock drift w.r.t. More...

struct tsch_log_t *	tsch_log_prepare_add (void)
	Prepare addition of a new log. More...

void	tsch_log_commit (void)
	Actually add the previously prepared log.

void	tsch_log_init (void)
	Initialize log module.

void	tsch_log_process_pending (void)
	Process pending log messages.

void	tsch_log_stop (void)
	Stop logging module.

void	tsch_packet_eackbuf_set_attr (uint8_t type, const packetbuf_attr_t val)
	Set a packet attribute for the current eack. More...

packetbuf_attr_t	tsch_packet_eackbuf_attr (uint8_t type)
	Return the value of a specified attribute. More...

int	tsch_packet_create_eack (uint8_t buf, uint16_t buf_size, const linkaddr_t dest_addr, uint8_t seqno, int16_t drift, int nack)
	Construct Enhanced ACK packet. More...

int	tsch_packet_parse_eack (const uint8_t buf, int buf_size, uint8_t seqno, frame802154_t frame, struct ieee802154_ies ies, uint8_t hdr_len)
	Parse enhanced ACK packet. More...

int	tsch_packet_create_eb (uint8_t hdr_len, uint8_t tsch_sync_ie_ptr)
	Create an EB packet directly in packetbuf. More...

int	tsch_packet_update_eb (uint8_t *buf, int buf_size, uint8_t tsch_sync_ie_offset)
	Update ASN in EB packet. More...

int	tsch_packet_parse_eb (const uint8_t buf, int buf_size, frame802154_t frame, struct ieee802154_ies ies, uint8_t hdrlen, int frame_without_mic)
	Parse EB. More...

void	tsch_packet_set_frame_pending (uint8_t *buf, int buf_size)
	Set frame pending bit in a packet (whose header was already build) More...

int	tsch_packet_get_frame_pending (uint8_t *buf, int buf_size)
	Get frame pending bit from a packet. More...

struct tsch_neighbor *	tsch_queue_add_nbr (const linkaddr_t *addr)
	Add a TSCH neighbor queue. More...

struct tsch_neighbor *	tsch_queue_get_nbr (const linkaddr_t *addr)
	Get a TSCH neighbor. More...

struct tsch_neighbor *	tsch_queue_get_time_source (void)
	Get the TSCH time source (we currently assume there is only one) More...

linkaddr_t *	tsch_queue_get_nbr_address (const struct tsch_neighbor *)
	Get the address of a neighbor. More...

int	tsch_queue_update_time_source (const linkaddr_t *new_addr)
	Update TSCH time source. More...

struct tsch_packet *	tsch_queue_add_packet (const linkaddr_t addr, uint8_t max_transmissions, mac_callback_t sent, void ptr)
	Add packet to neighbor queue. More...

int	tsch_queue_global_packet_count (void)
	Returns the number of packets currently in all TSCH queues. More...

int	tsch_queue_nbr_packet_count (const struct tsch_neighbor *n)
	Returns the number of packets currently a given neighbor queue (by pointer) More...

struct tsch_packet *	tsch_queue_remove_packet_from_queue (struct tsch_neighbor *n)
	Remove first packet from a neighbor queue. More...

void	tsch_queue_free_packet (struct tsch_packet *p)
	Free a packet. More...

int	tsch_queue_packet_sent (struct tsch_neighbor n, struct tsch_packet p, struct tsch_link *link, uint8_t mac_tx_status)
	Updates neighbor queue state after a transmission. More...

void	tsch_queue_reset (void)
	Reset neighbor queues module.

void	tsch_queue_free_unused_neighbors (void)
	Deallocate all neighbors with empty queue.

int	tsch_queue_is_empty (const struct tsch_neighbor *n)
	Is the neighbor queue empty? More...

struct tsch_packet *	tsch_queue_get_packet_for_nbr (const struct tsch_neighbor n, struct tsch_link link)
	Returns the first packet that can be sent from a queue on a given link. More...

struct tsch_packet *	tsch_queue_get_packet_for_dest_addr (const linkaddr_t addr, struct tsch_link link)
	Returns the first packet that can be sent to a given address on a given link. More...

struct tsch_packet *	tsch_queue_get_unicast_packet_for_any (struct tsch_neighbor *n, struct tsch_link link)
	Gets the head packet of any neighbor queue with zero backoff counter. More...

int	tsch_queue_backoff_expired (const struct tsch_neighbor *n)
	Is the neighbor backoff timer expired? More...

void	tsch_queue_backoff_reset (struct tsch_neighbor *n)
	Reset neighbor backoff. More...

void	tsch_queue_backoff_inc (struct tsch_neighbor *n)
	Increment backoff exponent of a given neighbor queue, pick a new window. More...

void	tsch_queue_update_all_backoff_windows (const linkaddr_t *dest_addr)
	Decrement backoff window for the queue(s) able to Tx to a given address. More...

void	tsch_queue_init (void)
	Initialize TSCH queue module.

void	tsch_rpl_callback_ka_sent (int status, int transmissions)
	Report statiscs from KA packet sent in RPL. More...

void	tsch_rpl_callback_joining_network (void)
	Let RPL know that TSCH joined a new network. More...

void	tsch_rpl_callback_leaving_network (void)
	Let RPL know that TSCH joined a new network. More...

void	tsch_rpl_callback_new_dio_interval (clock_time_t dio_interval)
	Set TSCH EB period based on current RPL DIO period. More...

void	tsch_rpl_callback_parent_switch (rpl_parent_t old, rpl_parent_t new)
	Set TSCH time source based on current RPL preferred parent. More...

int	tsch_rpl_check_dodag_joined (void)
	Check RPL has joined DODAG. More...

struct tsch_slotframe *	tsch_schedule_add_slotframe (uint16_t handle, uint16_t size)
	Creates and adds a new slotframe. More...

int	tsch_schedule_remove_all_slotframes (void)
	Removes all slotframes, resulting in an empty schedule. More...

int	tsch_schedule_remove_slotframe (struct tsch_slotframe *slotframe)
	Removes a slotframe. More...

struct tsch_slotframe *	tsch_schedule_get_slotframe_by_handle (uint16_t handle)
	Looks up a slotframe by handle. More...

struct tsch_link *	tsch_schedule_get_link_by_handle (uint16_t handle)
	Looks for a link from a handle. More...

struct tsch_link *	tsch_schedule_add_link (struct tsch_slotframe slotframe, uint8_t link_options, enum link_type link_type, const linkaddr_t address, uint16_t timeslot, uint16_t channel_offset, uint8_t do_remove)
	Adds a link to a slotframe. More...

int	tsch_schedule_remove_link (struct tsch_slotframe slotframe, struct tsch_link l)
	Removes a link. More...

int	tsch_schedule_remove_link_by_timeslot (struct tsch_slotframe *slotframe, uint16_t timeslot, uint16_t channel_offset)
	Removes a link from a slotframe and timeslot. More...

struct tsch_link *	tsch_schedule_get_link_by_timeslot (struct tsch_slotframe *slotframe, uint16_t timeslot, uint16_t channel_offset)
	Looks within a slotframe for a link with a given timeslot. More...

struct tsch_link *	tsch_schedule_get_next_active_link (struct tsch_asn_t asn, uint16_t time_offset, struct tsch_link **backup_link)
	Returns the next active link after a given ASN, and a backup link (for the same ASN, with Rx flag) More...

int	tsch_schedule_init (void)
	Module initialization, call only once at init. More...

void	tsch_schedule_create_minimal (void)
	Create a 6tisch minimal schedule with length TSCH_SCHEDULE_DEFAULT_LENGTH.

struct tsch_slotframe *	tsch_schedule_slotframe_head (void)
	Access the first item in the list of slotframes. More...

struct tsch_slotframe *	tsch_schedule_slotframe_next (struct tsch_slotframe *sf)
	Access the next item in the list of slotframes. More...

void	tsch_schedule_print (void)
	Prints out the current schedule (all slotframes and links)

unsigned int	tsch_security_mic_len (const frame802154_t *frame)
	Return MIC length. More...

unsigned int	tsch_security_secure_frame (uint8_t hdr, uint8_t outbuf, int hdrlen, int datalen, struct tsch_asn_t *asn)
	Protect a frame with encryption and/or MIC. More...

unsigned int	tsch_security_parse_frame (const uint8_t hdr, int hdrlen, int datalen, const frame802154_t frame, const linkaddr_t sender, struct tsch_asn_t asn)
	Parse and check a frame protected with encryption and/or MIC. More...

void	tsch_security_set_packetbuf_attr (uint8_t frame_type)
	Set packetbuf (or eackbuf) attributes depending on a given frame type. More...

int	tsch_is_locked (void)
	Checks if the TSCH lock is set. More...

int	tsch_get_lock (void)
	Takes the TSCH lock. More...

void	tsch_release_lock (void)
	Releases the TSCH lock.

static uint8_t	tsch_calculate_channel (struct tsch_asn_t *asn, uint16_t channel_offset)
	Returns a 802.15.4 channel from an ASN and channel offset. More...

uint64_t	tsch_get_network_uptime_ticks (void)
	Get the time, in clock ticks, since the TSCH network was started. More...

static void	tsch_radio_on (enum tsch_radio_state_on_cmd command)
	This function turns on the radio. More...

static void	tsch_radio_off (enum tsch_radio_state_off_cmd command)
	This function turns off the radio. More...

void	tsch_slot_operation_start (void)
	Start actual slot operation.

void	tsch_slot_operation_sync (rtimer_clock_t next_slot_start, struct tsch_asn_t *next_slot_asn)
	Set global time before starting slot operation, with a rtimer time and an ASN. More...

void	tsch_set_coordinator (int enable)
	Set the node as PAN coordinator. More...

void	tsch_set_pan_secured (int enable)
	Enable/disable security. More...

void	tsch_set_join_priority (uint8_t jp)
	Set the TSCH join priority (JP) More...

void	tsch_set_ka_timeout (uint32_t timeout)
	Set the desynchronization timeout after which a node sends a unicasst keep-alive (KA) to its time source. More...

void	tsch_set_eb_period (uint32_t period)
	Set the period at wich TSCH enhanced beacons (EBs) are sent. More...

void	tsch_schedule_keepalive (int immediate)
	Schedule a keep-alive transmission within [timeout*0.9, timeout[ Can be called from an interrupt. More...

void	tsch_disassociate (void)
	Leave the TSCH network we are currently in.

Variables
const tsch_timeslot_timing_usec	tsch_timeslot_timing_us_10000
	TSCH timing attributes and description. More...

const tsch_timeslot_timing_usec	tsch_timeslot_timing_us_10000
	TSCH timing attributes and description. More...

Detailed Description

The IEEE 802.15.4-2015 TimeSlotted Channel Hopping (TSCH) protocol.

Provides scheduled communication on top of a globally-synchronized network. Performs frequency hopping for enhanced reliability.

Enumeration Type Documentation

◆ link_type

enum link_type

802.15.4e link types.

LINK_TYPE_ADVERTISING_ONLY is an extra one: for EB-only links.

Definition at line 54 of file tsch-types.h.

◆ tsch_timeslot_timing_elements

enum tsch_timeslot_timing_elements

TSCH timeslot timing elements.

Used to index timeslot timing of different units, such as rtimer tick or micro-second

Definition at line 126 of file tsch-types.h.

Function Documentation

◆ tsch_adaptive_timesync_get_drift_ppm()

long int tsch_adaptive_timesync_get_drift_ppm ( void )

Gives the estimated clock drift w.r.t.

the time source in PPM (parts per million)

Returns: The time drift in PPM

Definition at line 223 of file tsch-adaptive-timesync.c.

◆ tsch_calculate_channel()

static uint8_t tsch_calculate_channel	(	struct tsch_asn_t *	asn,
		uint16_t	channel_offset
	)

static

Returns a 802.15.4 channel from an ASN and channel offset.

Basically adds The offset to the ASN and performs a hopping sequence lookup.

Parameters

asn	A given ASN
channel_offset	Given channel offset

Returns: The resulting channel

Definition at line 265 of file tsch-slot-operation.c.

◆ tsch_get_lock()

int tsch_get_lock ( void )

Takes the TSCH lock.

When the lock is taken, slot operation will be skipped until release.

Returns: 1 if the lock was successfully taken, 0 otherwise

Definition at line 193 of file tsch-slot-operation.c.

Referenced by tsch_schedule_init().

◆ tsch_get_network_uptime_ticks()

uint64_t tsch_get_network_uptime_ticks ( void )

Get the time, in clock ticks, since the TSCH network was started.

Returns: The network uptime, or -1 if the node is not part of a TSCH network.

Definition at line 386 of file tsch-slot-operation.c.

◆ tsch_is_locked()

int tsch_is_locked ( void )

Checks if the TSCH lock is set.

Accesses to global structures outside of interrupts must be done through the lock, unless the sturcutre has atomic read/write

Returns: 1 if the lock is taken, 0 otherwise

Definition at line 186 of file tsch-slot-operation.c.

Referenced by tsch_queue_free_unused_neighbors(), tsch_queue_get_nbr(), tsch_queue_get_packet_for_dest_addr(), tsch_queue_get_packet_for_nbr(), tsch_queue_get_time_source(), tsch_queue_get_unicast_packet_for_any(), tsch_queue_is_empty(), tsch_queue_remove_packet_from_queue(), tsch_queue_reset(), tsch_queue_update_all_backoff_windows(), tsch_queue_update_time_source(), and tsch_schedule_print().

◆ tsch_log_prepare_add()

struct tsch_log_t* tsch_log_prepare_add ( void )

Prepare addition of a new log.

Returns: A pointer to log structure if success, NULL otherwise

◆ tsch_packet_create_eack()

int tsch_packet_create_eack	(	uint8_t *	buf,
		uint16_t	buf_size,
		const linkaddr_t *	dest_addr,
		uint8_t	seqno,
		int16_t	drift,
		int	nack
	)

Construct Enhanced ACK packet.

Parameters

buf	The buffer where to build the EACK
buf_size	The buffer size
dest_addr	The link-layer address of the neighbor we are ACKing
seqno	The sequence number we are ACKing
drift	The time offset in usec measured at Rx of the packer we are ACKing
nack	Value of the NACK bit

Returns: The length of the packet that was created. -1 if failure.

Definition at line 93 of file tsch-packet.c.

◆ tsch_packet_create_eb()

int tsch_packet_create_eb	(	uint8_t *	hdr_len,
		uint8_t *	tsch_sync_ie_ptr
	)

Create an EB packet directly in packetbuf.

Parameters

hdr_len	A pointer where to store the length of the created header
tsch_sync_ie_ptr	A pointer where to store the address of the TSCH synchronization IE

Returns: The total length of the EB

Definition at line 220 of file tsch-packet.c.

◆ tsch_packet_eackbuf_attr()

packetbuf_attr_t tsch_packet_eackbuf_attr ( uint8_t type )

Return the value of a specified attribute.

Parameters

type	The attribute identifier

Returns: The attribute value

Definition at line 86 of file tsch-packet.c.

◆ tsch_packet_eackbuf_set_attr()

void tsch_packet_eackbuf_set_attr	(	uint8_t	type,
		const packetbuf_attr_t	val
	)

Set a packet attribute for the current eack.

We not use standard packetbuf for eacks because these are generated from interrupt context.

Parameters

type	The attribute identifier
val	The attribute value

Definition at line 78 of file tsch-packet.c.

◆ tsch_packet_get_frame_pending()

int tsch_packet_get_frame_pending	(	uint8_t *	buf,
		int	buf_size
	)

Get frame pending bit from a packet.

Parameters

buf	The buffer where the packet resides
buf_size	The buffer size

Returns: The value of the frame pending bit, 1 or 0

Definition at line 461 of file tsch-packet.c.

◆ tsch_packet_parse_eack()

int tsch_packet_parse_eack	(	const uint8_t *	buf,
		int	buf_size,
		uint8_t	seqno,
		frame802154_t *	frame,
		struct ieee802154_ies *	ies,
		uint8_t *	hdr_len
	)

Parse enhanced ACK packet.

Parameters

buf	The buffer where to parse the EACK from
buf_size	The buffer size
seqno	The sequence number we are expecting
frame	The frame structure where to store parsed fields
ies	The IE structure where to store parsed IEs
hdr_len	A pointer where to store the length of the parsed header

Returns: 1 if the EACK is correct and acknowledges the specified frame, 0 otherwise

Definition at line 155 of file tsch-packet.c.

◆ tsch_packet_parse_eb()

int tsch_packet_parse_eb	(	const uint8_t *	buf,
		int	buf_size,
		frame802154_t *	frame,
		struct ieee802154_ies *	ies,
		uint8_t *	hdrlen,
		int	frame_without_mic
	)

Parse EB.

Parameters

buf	The buffer where to parse the EB from
buf_size	The buffer sizecting
frame	The frame structure where to store parsed fields
ies	The IE structure where to store parsed IEs
hdrlen	A pointer where to store the length of the parsed header
frame_without_mic	When set, the security MIC will not be parsed

Returns: The length of the parsed EB

Definition at line 387 of file tsch-packet.c.

◆ tsch_packet_set_frame_pending()

void tsch_packet_set_frame_pending	(	uint8_t *	buf,
		int	buf_size
	)

Set frame pending bit in a packet (whose header was already build)

Parameters

buf	The buffer where the packet resides
buf_size	The buffer size

Definition at line 454 of file tsch-packet.c.

◆ tsch_packet_update_eb()

int tsch_packet_update_eb	(	uint8_t *	buf,
		int	buf_size,
		uint8_t	tsch_sync_ie_offset
	)

Update ASN in EB packet.

Parameters

buf	The buffer that contains the EB
buf_size	The buffer size
tsch_sync_ie_offset	The offset of the TSCH synchronization IE, in which the ASN is to be written

Returns: 1 if success, 0 otherwise

Definition at line 377 of file tsch-packet.c.

◆ tsch_queue_add_nbr()

struct tsch_neighbor * tsch_queue_add_nbr ( const linkaddr_t * addr )

Add a TSCH neighbor queue.

Parameters

addr	The link-layer address of the neighbor to be added

Definition at line 81 of file tsch-queue.c.

◆ tsch_queue_add_packet()

struct tsch_packet * tsch_queue_add_packet	(	const linkaddr_t *	addr,
		uint8_t	max_transmissions,
		mac_callback_t	sent,
		void *	ptr
	)

Add packet to neighbor queue.

Use same lockfree implementation as ringbuf.c (put is atomic)

Parameters

addr	The address of the targetted neighbor, &tsch_broadcast_address for broadcast
max_transmissions	The number of MAC retries
sent	The MAC packet sent callback
ptr	The MAC packet send callback parameter

Returns: The newly created packet if any, NULL otherwise

Definition at line 229 of file tsch-queue.c.

◆ tsch_queue_backoff_expired()

int tsch_queue_backoff_expired ( const struct tsch_neighbor * n )

Is the neighbor backoff timer expired?

Parameters

n	The neighbor queue

Returns: 1 if the backoff has expired (neighbor ready to transmit on a shared link), 0 otherwise

Definition at line 475 of file tsch-queue.c.

◆ tsch_queue_backoff_inc()

void tsch_queue_backoff_inc ( struct tsch_neighbor * n )

Increment backoff exponent of a given neighbor queue, pick a new window.

Parameters

n	The neighbor queue

Definition at line 490 of file tsch-queue.c.

◆ tsch_queue_backoff_reset()

void tsch_queue_backoff_reset ( struct tsch_neighbor * n )

Reset neighbor backoff.

Parameters

n	The neighbor queue

Definition at line 482 of file tsch-queue.c.

◆ tsch_queue_free_packet()

void tsch_queue_free_packet ( struct tsch_packet * p )

Free a packet.

Parameters

p	The packet to be freed

Definition at line 314 of file tsch-queue.c.

◆ tsch_queue_get_nbr()

struct tsch_neighbor * tsch_queue_get_nbr ( const linkaddr_t * addr )

Get a TSCH neighbor.

Parameters

addr	The link-layer address of the neighbor we are looking for

Returns: A pointer to the neighbor queue, NULL if not found

Definition at line 110 of file tsch-queue.c.

References tsch_is_locked().

Referenced by tsch_queue_get_packet_for_dest_addr().

◆ tsch_queue_get_nbr_address()

linkaddr_t * tsch_queue_get_nbr_address ( const struct tsch_neighbor * )

Get the address of a neighbor.

Returns: The link-layer address of the neighbor.

Definition at line 135 of file tsch-queue.c.

◆ tsch_queue_get_packet_for_dest_addr()

struct tsch_packet * tsch_queue_get_packet_for_dest_addr	(	const linkaddr_t *	addr,
		struct tsch_link *	link
	)

Returns the first packet that can be sent to a given address on a given link.

Parameters

addr	The target link-layer address
link	The link

Returns: The next packet to be sent for to the given address on the given link, if any, else NULL

Definition at line 440 of file tsch-queue.c.

References tsch_is_locked(), tsch_queue_get_nbr(), and tsch_queue_get_packet_for_nbr().

◆ tsch_queue_get_packet_for_nbr()

struct tsch_packet * tsch_queue_get_packet_for_nbr	(	const struct tsch_neighbor *	n,
		struct tsch_link *	link
	)

Returns the first packet that can be sent from a queue on a given link.

Parameters

n	The neighbor queue
link	The link

Returns: The next packet to be sent for the neighbor on the given link, if any, else NULL

Definition at line 412 of file tsch-queue.c.

References tsch_is_locked().

Referenced by tsch_queue_get_packet_for_dest_addr().

◆ tsch_queue_get_time_source()

struct tsch_neighbor * tsch_queue_get_time_source ( void )

Get the TSCH time source (we currently assume there is only one)

Returns: The neighbor queue associated to the time source

Definition at line 120 of file tsch-queue.c.

References tsch_is_locked().

◆ tsch_queue_get_unicast_packet_for_any()

struct tsch_packet * tsch_queue_get_unicast_packet_for_any	(	struct tsch_neighbor **	n,
		struct tsch_link *	link
	)

Gets the head packet of any neighbor queue with zero backoff counter.

Parameters

n	A pointer where to store the neighbor queue to be used for Tx
link	The link to be used for Tx

Returns: The packet if any, else NULL

Definition at line 451 of file tsch-queue.c.

References tsch_is_locked().

◆ tsch_queue_global_packet_count()

int tsch_queue_global_packet_count ( void )

Returns the number of packets currently in all TSCH queues.

Returns: The number of packets currently in all TSCH queues

Definition at line 279 of file tsch-queue.c.

◆ tsch_queue_is_empty()

int tsch_queue_is_empty ( const struct tsch_neighbor * n )

Is the neighbor queue empty?

Parameters

n	The neighbor queue

Returns: 1 if empty, 0 otherwise

Definition at line 405 of file tsch-queue.c.

References tsch_is_locked().

◆ tsch_queue_nbr_packet_count()

int tsch_queue_nbr_packet_count ( const struct tsch_neighbor * n )

Returns the number of packets currently a given neighbor queue (by pointer)

Parameters

n	The neighbor we are interested in

Returns: The number of packets in the neighbor's queue

Definition at line 286 of file tsch-queue.c.

◆ tsch_queue_packet_sent()

int tsch_queue_packet_sent	(	struct tsch_neighbor *	n,
		struct tsch_packet *	p,
		struct tsch_link *	link,
		uint8_t	mac_tx_status
	)

Updates neighbor queue state after a transmission.

Parameters

n	The neighbor queue we just sent from
p	The packet that was just sent
link	The TSCH link used for Tx
mac_tx_status	The MAC status (see mac.h)

Returns: 1 if the packet remains in queue after the call, 0 if it was removed

Definition at line 324 of file tsch-queue.c.

◆ tsch_queue_remove_packet_from_queue()

struct tsch_packet * tsch_queue_remove_packet_from_queue ( struct tsch_neighbor * n )

Remove first packet from a neighbor queue.

The packet is stored in a separate dequeued packet list, for later processing.

Parameters

n	The neighbor queue

Returns: The packet that was removed if any, NULL otherwise

Definition at line 296 of file tsch-queue.c.

References tsch_is_locked().

◆ tsch_queue_update_all_backoff_windows()

void tsch_queue_update_all_backoff_windows ( const linkaddr_t * dest_addr )

Decrement backoff window for the queue(s) able to Tx to a given address.

Parameters

dest_addr The target address, &tsch_broadcast_address for broadcast

Definition at line 505 of file tsch-queue.c.

References linkaddr_cmp(), and tsch_is_locked().

◆ tsch_queue_update_time_source()

int tsch_queue_update_time_source ( const linkaddr_t * new_addr )

Update TSCH time source.

Parameters

new_addr The address of the new TSCH time source

Definition at line 142 of file tsch-queue.c.

References tsch_is_locked().

◆ tsch_radio_off()

static void tsch_radio_off ( enum tsch_radio_state_off_cmd command )

static

This function turns off the radio.

In the same way as for tsch_radio_on(), it depends on the value of TSCH_RADIO_ON_DURING_TIMESLOT constant:

if enabled, the radio is turned off at the end of the slot
if disabled, the radio is turned off within the slot, directly after Tx'ing or Rx'ing a packet or Tx'ing an ACK.

Definition at line 451 of file tsch-slot-operation.c.

◆ tsch_radio_on()

static void tsch_radio_on ( enum tsch_radio_state_on_cmd command )

static

This function turns on the radio.

Its semantics is dependent on the value of TSCH_RADIO_ON_DURING_TIMESLOT constant:

if enabled, the radio is turned on at the start of the slot
if disabled, the radio is turned on within the slot, directly before the packet Rx guard time and ACK Rx guard time.

Definition at line 420 of file tsch-slot-operation.c.

◆ tsch_rpl_callback_joining_network()

void tsch_rpl_callback_joining_network ( void )

Let RPL know that TSCH joined a new network.

To use, set TSCH_CALLBACK_JOINING_NETWORK to tsch_rpl_callback_joining_network

◆ tsch_rpl_callback_ka_sent()

void tsch_rpl_callback_ka_sent	(	int	status,
		int	transmissions
	)

Report statiscs from KA packet sent in RPL.

To use, set TSCH_CALLBACK_KA_SENT to tsch_rpl_callback_ka_sent

Parameters

status	The packet sent status
transmissions	The total number of transmissions

◆ tsch_rpl_callback_leaving_network()

void tsch_rpl_callback_leaving_network ( void )

Let RPL know that TSCH joined a new network.

Triggers a local repair. To use, set TSCH_CALLBACK_LEAVING_NETWORK to tsch_rpl_callback_leaving_network

◆ tsch_rpl_callback_new_dio_interval()

void tsch_rpl_callback_new_dio_interval ( clock_time_t dio_interval )

Set TSCH EB period based on current RPL DIO period.

To use, set RPL_CALLBACK_NEW_DIO_INTERVAL to tsch_rpl_callback_new_dio_interval

Parameters

dio_interval The new DIO interval in clock ticks

◆ tsch_rpl_callback_parent_switch()

void tsch_rpl_callback_parent_switch	(	rpl_parent_t *	old,
		rpl_parent_t *	new
	)

Set TSCH time source based on current RPL preferred parent.

To use, set RPL_CALLBACK_PARENT_SWITCH to tsch_rpl_callback_parent_switch

Parameters

old	The old RPL parent
new	The new RPL parent

◆ tsch_rpl_check_dodag_joined()

int tsch_rpl_check_dodag_joined ( void )

Check RPL has joined DODAG.

To use, set TSCH_RPL_CHECK_DODAG_JOINED tsch_rpl_check_dodag_joined

Returns: 1 if joined, 0 otherwise

◆ tsch_schedule_add_link()

struct tsch_link* tsch_schedule_add_link	(	struct tsch_slotframe *	slotframe,
		uint8_t	link_options,
		enum link_type	link_type,
		const linkaddr_t *	address,
		uint16_t	timeslot,
		uint16_t	channel_offset,
		uint8_t	do_remove
	)

Adds a link to a slotframe.

Parameters

slotframe	The slotframe that will contain the new link
link_options	The link options, as a bitfield (LINK_OPTION_* flags)
link_type	The link type (advertising, normal)
address	The link address of the intended destination. Use &tsch_broadcast_address for a slot towards any neighbor
timeslot	The link timeslot within the slotframe
channel_offset	The link channel offset
do_remove	Whether to remove an old link at this timeslot and channel offset

Returns: A pointer to the new link, NULL if failure

Definition at line 216 of file tsch-schedule.c.

◆ tsch_schedule_add_slotframe()

struct tsch_slotframe * tsch_schedule_add_slotframe	(	uint16_t	handle,
		uint16_t	size
	)

Creates and adds a new slotframe.

Parameters

handle	the slotframe handle
size	the slotframe size

Returns: the new slotframe, NULL if failure

Definition at line 73 of file tsch-schedule.c.

Referenced by tsch_schedule_create_minimal().

◆ tsch_schedule_get_link_by_handle()

struct tsch_link * tsch_schedule_get_link_by_handle ( uint16_t handle )

Looks for a link from a handle.

Parameters

handle The target handle

Returns: The link with required handle, if any. Otherwise, NULL

Definition at line 156 of file tsch-schedule.c.

◆ tsch_schedule_get_link_by_timeslot()

struct tsch_link * tsch_schedule_get_link_by_timeslot	(	struct tsch_slotframe *	slotframe,
		uint16_t	timeslot,
		uint16_t	channel_offset
	)

Looks within a slotframe for a link with a given timeslot.

Parameters

slotframe	The desired slotframe
timeslot	The desired timeslot
channel_offset	The desired channel offset

Returns: The link if found, NULL otherwise

Definition at line 362 of file tsch-schedule.c.

◆ tsch_schedule_get_next_active_link()

struct tsch_link * tsch_schedule_get_next_active_link	(	struct tsch_asn_t *	asn,
		uint16_t *	time_offset,
		struct tsch_link **	backup_link
	)

Returns the next active link after a given ASN, and a backup link (for the same ASN, with Rx flag)

Parameters

asn	The base ASN, from which we look for the next active link
time_offset	A pointer to uint16_t where to store the time offset between base ASN and link found
backup_link	A pointer where to write the address of a backup link, to be executed should the original be no longer active at wakeup

Returns: The next active link if any, NULL otherwise

Definition at line 406 of file tsch-schedule.c.

◆ tsch_schedule_get_slotframe_by_handle()

struct tsch_slotframe * tsch_schedule_get_slotframe_by_handle ( uint16_t handle )

Looks up a slotframe by handle.

Parameters

handle the slotframe handle

Returns: the slotframe with required handle, if any. NULL otherwise.

Definition at line 140 of file tsch-schedule.c.

◆ tsch_schedule_init()

int tsch_schedule_init ( void )

Module initialization, call only once at init.

Returns: 1 if success, 0 if failure

Definition at line 488 of file tsch-schedule.c.

References list_init(), memb_init(), tsch_get_lock(), and tsch_release_lock().

◆ tsch_schedule_keepalive()

void tsch_schedule_keepalive ( int immediate )

Schedule a keep-alive transmission within [timeout*0.9, timeout[ Can be called from an interrupt.

See also: tsch_set_ka_timeout

Parameters

immediate send immediately when 1, schedule using current timeout when 0

Definition at line 333 of file tsch.c.

◆ tsch_schedule_remove_all_slotframes()

int tsch_schedule_remove_all_slotframes ( void )

Removes all slotframes, resulting in an empty schedule.

Returns: 1 if success, 0 if failure

Definition at line 104 of file tsch-schedule.c.

References list_head(), and tsch_schedule_remove_slotframe().

Referenced by tsch_schedule_create_minimal().

◆ tsch_schedule_remove_link()

int tsch_schedule_remove_link	(	struct tsch_slotframe *	slotframe,
		struct tsch_link *	l
	)

Removes a link.

Parameters

slotframe	The slotframe the link belongs to
l	The link to be removed

Returns: 1 if success, 0 if failure

Definition at line 287 of file tsch-schedule.c.

◆ tsch_schedule_remove_link_by_timeslot()

int tsch_schedule_remove_link_by_timeslot	(	struct tsch_slotframe *	slotframe,
		uint16_t	timeslot,
		uint16_t	channel_offset
	)

Removes a link from a slotframe and timeslot.

Parameters

slotframe	The slotframe where to look for the link
timeslot	The timeslot where to look for the link within the target slotframe
channel_offset	The channel offset where to look for the link within the target slotframe

Returns: 1 if success, 0 if failure

Definition at line 338 of file tsch-schedule.c.

◆ tsch_schedule_remove_slotframe()

int tsch_schedule_remove_slotframe ( struct tsch_slotframe * slotframe )

Removes a slotframe.

Parameters

slotframe The slotframe to be removed

Returns: 1 if success, 0 if failure

Definition at line 117 of file tsch-schedule.c.

Referenced by tsch_schedule_remove_all_slotframes().

◆ tsch_schedule_slotframe_head()

struct tsch_slotframe * tsch_schedule_slotframe_head ( void )

Access the first item in the list of slotframes.

Returns: The first slotframe in the schedule if any, NULL otherwise

Definition at line 522 of file tsch-schedule.c.

References list_head().

◆ tsch_schedule_slotframe_next()

struct tsch_slotframe * tsch_schedule_slotframe_next ( struct tsch_slotframe * sf )

Access the next item in the list of slotframes.

Parameters

sf	The current slotframe (item in the list)

Returns: The next slotframe if any, NULL otherwise

Definition at line 528 of file tsch-schedule.c.

References list_item_next().

◆ tsch_security_mic_len()

unsigned int tsch_security_mic_len ( const frame802154_t * frame )

Return MIC length.

Returns: The length of MIC (>= 0)

Definition at line 126 of file tsch-security.c.

◆ tsch_security_parse_frame()

unsigned int tsch_security_parse_frame	(	const uint8_t *	hdr,
		int	hdrlen,
		int	datalen,
		const frame802154_t *	frame,
		const linkaddr_t *	sender,
		struct tsch_asn_t *	asn
	)

Parse and check a frame protected with encryption and/or MIC.

Return values

0	On error or security check failure (insecure frame)
1	On success or no need for security check (good frame)

Definition at line 207 of file tsch-security.c.

◆ tsch_security_secure_frame()

unsigned int tsch_security_secure_frame	(	uint8_t *	hdr,
		uint8_t *	outbuf,
		int	hdrlen,
		int	datalen,
		struct tsch_asn_t *	asn
	)

Protect a frame with encryption and/or MIC.

Returns: The length of a generated MIC (>= 0)

Definition at line 136 of file tsch-security.c.

◆ tsch_security_set_packetbuf_attr()

void tsch_security_set_packetbuf_attr ( uint8_t frame_type )

Set packetbuf (or eackbuf) attributes depending on a given frame type.

Parameters

frame_type The frame type (FRAME802154_BEACONFRAME etc.)

Definition at line 276 of file tsch-security.c.

◆ tsch_set_coordinator()

void tsch_set_coordinator ( int enable )

Set the node as PAN coordinator.

Parameters

enable 1 to be coordinator, 0 to be a node

Definition at line 168 of file tsch.c.

◆ tsch_set_eb_period()

void tsch_set_eb_period ( uint32_t period )

Set the period at wich TSCH enhanced beacons (EBs) are sent.

The period can not be set to exceed TSCH_MAX_EB_PERIOD. Set to 0 to stop sending EBs. Actual transmissions are jittered, spaced by a random number within [period*0.75, period[ If RPL is used, the period will be automatically reset by RPL equal to the DIO period whenever the DIO period changes. Hence, calling tsch_set_eb_period(0) is NOT sufficient to disable sending EB! To do that, either configure the node in RPL leaf mode, or use static config for TSCH (define TSCH_CONF_EB_PERIOD 0).

Parameters

period The period in Clock ticks.

Definition at line 197 of file tsch.c.

◆ tsch_set_join_priority()

void tsch_set_join_priority ( uint8_t jp )

Set the TSCH join priority (JP)

Parameters

jp	the new join priority

Definition at line 184 of file tsch.c.

◆ tsch_set_ka_timeout()

void tsch_set_ka_timeout ( uint32_t timeout )

Set the desynchronization timeout after which a node sends a unicasst keep-alive (KA) to its time source.

Set to 0 to stop sending KAs. The actual timeout is a random number within [timeout*0.9, timeout[ Can be called from an interrupt.

Parameters

timeout The timeout in Clock ticks.

Definition at line 190 of file tsch.c.

◆ tsch_set_pan_secured()

void tsch_set_pan_secured ( int enable )

Enable/disable security.

If done at the coordinator, the Information will be included in EBs, and all nodes will adopt the same security level. Enabling requires compilation with LLSEC802154_ENABLED set. Note: when LLSEC802154_ENABLED is set, nodes boot with security enabled.

Parameters

enable 1 to enable security, 0 to disable it

Definition at line 178 of file tsch.c.

◆ tsch_slot_operation_sync()

void tsch_slot_operation_sync	(	rtimer_clock_t	next_slot_start,
		struct tsch_asn_t *	next_slot_asn
	)

Set global time before starting slot operation, with a rtimer time and an ASN.

Parameters

next_slot_start	the time to the start of the next slot, in rtimer ticks
next_slot_asn	the ASN of the next slot

Definition at line 1196 of file tsch-slot-operation.c.

◆ tsch_timesync_adaptive_compensate()

int32_t tsch_timesync_adaptive_compensate ( rtimer_clock_t delta_ticks )

Computes time compensation for a given point in the future.

Parameters

delta_ticks The number of ticks in the future we want to calculate compensation for

Returns: The time compensation

Definition at line 213 of file tsch-adaptive-timesync.c.

◆ tsch_timesync_update()

void tsch_timesync_update	(	struct tsch_neighbor *	n,
		uint16_t	time_delta_asn,
		int32_t	drift_correction
	)

Updates timesync information for a given neighbor.

Parameters

n	The neighbor
time_delta_asn	ASN time delta since last synchronization, i.e. number of slots elapsed
drift_correction	The measured drift in ticks since last synchronization

Definition at line 208 of file tsch-adaptive-timesync.c.

Variable Documentation

◆ tsch_timeslot_timing_us_10000 [1/2]

const tsch_timeslot_timing_usec tsch_timeslot_timing_us_10000

Initial value:

= {
   1800, 
    128, 
   2120, 
  (2120 - (TSCH_CONF_RX_WAIT / 2)), 
    800, 
   1000, 
  TSCH_CONF_RX_WAIT, 
    400, 
    192, 
   2400, 
   4256, 
  10000, 
}

TSCH timing attributes and description.

All timings are in usec.

CCAOffset -> time between the beginning of timeslot and start of CCA CCA -> duration of CCA (CCA is NOT ENABLED by default) TxOffset -> time between beginning of the timeslot and start of frame TX (end of SFD) RxOffset -> beginning of the timeslot to when the receiver shall be listening RxAckDelay -> end of frame to when the transmitter shall listen for ACK TxAckDelay -> end of frame to the start of ACK tx RxWait -> time to wait for start of frame (Guard time) AckWait -> min time to wait for start of an ACK frame RxTx -> receive-to-transmit switch time (NOT USED) MaxAck -> TX time to send a max length ACK MaxTx -> TX time to send the max length frame

The TSCH timeslot structure is described in the IEEE 802.15.4-2015 standard, in particular in the Figure 6-30.

The default timeslot timing in the standard is a guard time of 2200 us, a Tx offset of 2120 us and a Rx offset of 1120 us. As a result, the listening device has a guard time not centered on the expected Tx time. This is to be fixed in the next iteration of the standard. This can be enabled with: TxOffset: 2120 RxOffset: 1120 RxWait: 2200

Instead, we align the Rx guard time on expected Tx time. The Rx guard time is user-configurable with TSCH_CONF_RX_WAIT. (TxOffset - (RxWait / 2)) instead

Definition at line 81 of file tsch-timeslot-timing.c.

◆ tsch_timeslot_timing_us_10000 [2/2]

const tsch_timeslot_timing_usec tsch_timeslot_timing_us_10000

TSCH timing attributes and description.

All timings are in usec.

CCAOffset -> time between the beginning of timeslot and start of CCA CCA -> duration of CCA (CCA is NOT ENABLED by default) TxOffset -> time between beginning of the timeslot and start of frame TX (end of SFD) RxOffset -> beginning of the timeslot to when the receiver shall be listening RxAckDelay -> end of frame to when the transmitter shall listen for ACK TxAckDelay -> end of frame to the start of ACK tx RxWait -> time to wait for start of frame (Guard time) AckWait -> min time to wait for start of an ACK frame RxTx -> receive-to-transmit switch time (NOT USED) MaxAck -> TX time to send a max length ACK MaxTx -> TX time to send the max length frame

The TSCH timeslot structure is described in the IEEE 802.15.4-2015 standard, in particular in the Figure 6-30.

The default timeslot timing in the standard is a guard time of 2200 us, a Tx offset of 2120 us and a Rx offset of 1120 us. As a result, the listening device has a guard time not centered on the expected Tx time. This is to be fixed in the next iteration of the standard. This can be enabled with: TxOffset: 2120 RxOffset: 1120 RxWait: 2200

Instead, we align the Rx guard time on expected Tx time. The Rx guard time is user-configurable with TSCH_CONF_RX_WAIT. (TxOffset - (RxWait / 2)) instead

Definition at line 81 of file tsch-timeslot-timing.c.

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ link_type

◆ tsch_timeslot_timing_elements

Function Documentation

◆ tsch_adaptive_timesync_get_drift_ppm()

◆ tsch_calculate_channel()

◆ tsch_get_lock()

◆ tsch_get_network_uptime_ticks()

◆ tsch_is_locked()

◆ tsch_log_prepare_add()

◆ tsch_packet_create_eack()

◆ tsch_packet_create_eb()

◆ tsch_packet_eackbuf_attr()

◆ tsch_packet_eackbuf_set_attr()

◆ tsch_packet_get_frame_pending()

◆ tsch_packet_parse_eack()

◆ tsch_packet_parse_eb()

◆ tsch_packet_set_frame_pending()

◆ tsch_packet_update_eb()

◆ tsch_queue_add_nbr()

◆ tsch_queue_add_packet()

◆ tsch_queue_backoff_expired()

◆ tsch_queue_backoff_inc()

◆ tsch_queue_backoff_reset()

◆ tsch_queue_free_packet()

◆ tsch_queue_get_nbr()

◆ tsch_queue_get_nbr_address()

◆ tsch_queue_get_packet_for_dest_addr()

◆ tsch_queue_get_packet_for_nbr()

◆ tsch_queue_get_time_source()

◆ tsch_queue_get_unicast_packet_for_any()

◆ tsch_queue_global_packet_count()

◆ tsch_queue_is_empty()

◆ tsch_queue_nbr_packet_count()

◆ tsch_queue_packet_sent()

◆ tsch_queue_remove_packet_from_queue()

◆ tsch_queue_update_all_backoff_windows()

◆ tsch_queue_update_time_source()

◆ tsch_radio_off()

◆ tsch_radio_on()

◆ tsch_rpl_callback_joining_network()

◆ tsch_rpl_callback_ka_sent()

◆ tsch_rpl_callback_leaving_network()

◆ tsch_rpl_callback_new_dio_interval()

◆ tsch_rpl_callback_parent_switch()

◆ tsch_rpl_check_dodag_joined()

◆ tsch_schedule_add_link()

◆ tsch_schedule_add_slotframe()

◆ tsch_schedule_get_link_by_handle()

◆ tsch_schedule_get_link_by_timeslot()

◆ tsch_schedule_get_next_active_link()

◆ tsch_schedule_get_slotframe_by_handle()

◆ tsch_schedule_init()

◆ tsch_schedule_keepalive()

◆ tsch_schedule_remove_all_slotframes()

◆ tsch_schedule_remove_link()

◆ tsch_schedule_remove_link_by_timeslot()

◆ tsch_schedule_remove_slotframe()

◆ tsch_schedule_slotframe_head()

◆ tsch_schedule_slotframe_next()

◆ tsch_security_mic_len()

◆ tsch_security_parse_frame()

◆ tsch_security_secure_frame()

◆ tsch_security_set_packetbuf_attr()

◆ tsch_set_coordinator()

◆ tsch_set_eb_period()

◆ tsch_set_join_priority()

◆ tsch_set_ka_timeout()

◆ tsch_set_pan_secured()

◆ tsch_slot_operation_sync()

◆ tsch_timesync_adaptive_compensate()

◆ tsch_timesync_update()