Skip to content

Network layer. Commands Description. Commands Examples

Jump to bottom Edit New page
vkebkal edited this page Aug 27, 2018 · 36 revisions

Table of Contents

General section

Each NL command must be answered with its synchronous answer. The possible synchronous answered are described in the raw "Answer" in the command specifications below. If no synchronous answer is received during 1 second, this must be treated as an error.

Help

Format ?
Answer human readable text
Tuple for command {nl, get, help}
Tuple for answer {nl, help, Bin}

Example: 

?
=========================================== HELP ===========================================
?                                              	- List of all commands
===================================== Send and receive ======================================
NL,send,[<Type>],[<Datalen>],<Dst>,<Data>       - Send data, <Type> and <Datalen> - optional
NL,recv,<Datalen>,<Src>,<Dst>,<Data>            - Recv data
===================================== Immediate response =====================================
NL,send,0                                       - Message was accepted and will be transmitted
NL,error                                       	- Message was not accepted and will be dropped
NL,error,norouting                      	- Message was not accepted and will be dropped, no routing specified, only for static routing
NL,busy                                       	- NL is busy, message will be dropped
...

Version

Format NL,get,version
Answer NL,version,Major,Minor,Name
Tuple for command {nl, get, version}
Tuple for answer {nl, version, Major, Minor, Description}

Example: 

NL,get,version
NL,version,0,1,mux:emb

Sending data

Send data to a remote address

Format NL,send[,Type],[Datalen],Dst,Data Type: optional parameter, used for polling application, sensitive / tolerant / broadcast / alarm
Datalen: optional
Answer NL,send,PC
NL,send,error
NL,send,busy 		PC is currently 0, it is reserved for future use
Asynchronous Answer NL,delivered,PC,Src,Dst
NL,failed,PC,Src,Dst 		PC is currently 0, it is reserved for future use
Tuple for command {nl, send, Dst, Data},
{nl, send, Type, Dst, Data},
{nl, send, Datalen, Dst, Data},
{nl, send, Type, Datalen, Dst, Data} 		Dst: integer
Data: binary
Type: atom
Tuple for answer {nl, send, PC}
{nl, send, error}
{nl, send, busy}
Tuple for asynchronous answer {nl, failed, PC, Src, Dst}
{nl, delivered, PC, Src, Dst}

Send data

Example: 

 # Send data with data length 4 bytes to remote address 2
NL,send,4,2,test
NL,send,0

 # Send data to remote address 2
NL,send,,2,test
NL,send,0

 # Brodacst data through the whole network, only for flooding protocol (63 is the maximum address in the newtork)
NL,send,,63,test
NL,send,0

 # Error, command was not accepted and will be dropped, wrong data length
NL,send,2,2,test
NL,send,error

 # Channel is busy, message was not accepted and will be dropped
NL,send,4,2,test
NL,send,busy

Asynchronous answer is end-to-end and is only supported for routing protocols with acknowledge. 

 # Send data with data length 4 bytes to remote address 2.
 # Data was successfully delivered to remote address 2
NL,send,4,2,test
NL,send,0
NL,delivered,0,1,2

 # Send data with data length 4 bytes to remote address 2.
 # Data failed to deliver to remote address 2
NL,send,4,2,test
NL,send,0
NL,failed,0,1,2

Send data for polling application

We have 4 types of messages: sensitive, tolerant, broadcast and alarm (see the description below)

Tolerant Tolerant messages are queued and are never dropped. A tolerant message will be sent if its remote address is requested during the polling loop. The message will be removed from the queue if it was successfully delivered.
Sensitive Sensitive messages are queued in limited numbers. If there are more than 3 of them, the oldest one will be dropped. A sensitive message will be sent if its remote address is requested during the polling loop. The message will be removed from the queue if it was successfully delivered.
Broadcast Broadcast messages are not queued. This message type has priority over tolerant/sensitive messages and will be sent first, other data will sent later. The message will be removed from the queue if it was successfully delivered.
Alarm An alarm message will be broadcasted through the whole network immediately while everything else will be ignored. The polling loop will be stopped.

Example: 

 # Send tolerant data with data length 4 bytes to remote address 2.
 # This message will be queued and will be sent if it will be requested in the polling loop
NL,send,tolerant,4,2,test
NL,send,0
 # Send sensitive data with data length 4 bytes to remote address 2.
 # This message will be queued and dropped if the limit of queue is more than 3.
NL,send,sensitive,4,2,test
NL,send,0
 # Send broadcast message with data length 4 bytes to remote address 2. This message will not be queued.
 # Ignoring all other messages, it will be sent as soon as possible according to the polling loop.
NL,send,broadcast,4,2,test
NL,send,0
 # Send alarm message. Everything will be ignored. The polling will be stopped.
 # The alarm messages will be broadcasted through the whole network.
NL,send,alarm,4,2,test
NL,send,0

Receiving data

Format NL,recv,Datalen,Src,Dst,Data
Tuples for asynchronous answers: {nl, recv, Datalen, Src, Dst, Data} Datalen: integer
Src: integer
Dst: integer
Data: binary

Receive data

Example: 

 # Local address 2 received data (length 4 bytes) from remote address 1
NL,recv,4,1,2,test

Local address commands

Set local address

Format NL,set,address,Addr
Answer NL,address,Addr
NL,address,error
Tuples for command: {nl, set, Addr} Addr:integer
Tuples for answers: {nl, address, Addr}
{nl, address, error}

Example: 

 # Set local address to address 1
NL,set,address,1
NL,address,1
 # Set local address to address b. Address can be only integer
NL,set,address,b
NL,address,error

Get local address

Format NL,get,address
Answer NL,address,Addr
Tuples for command: {nl, get, Addr}
Tuples for answers: {nl, address, Addr}
Addr: integer

Example: 

 # Get local address, local address is 1
NL,get,address
NL,address,1

Protocol commands

Get list of all supported routing protocols

Format NL,get,protocols
Answer NL,protocols,Protocol1,Protocol2,..,ProtocolN
Tuple for command {nl,get,protocols}
Tuple for answer {nl,protocols,ProtocolList} ProtocolList:list of atoms

Example: 

NL,get,protocols
NL,protocols,staticr,staticrack,sncfloodr,sncfloodrack,sncfloodpfr,sncfloodpfrack

Get current routing protocol

Format NL,get,protocol
Answer NL,protocol,Protocol
Tuple for command {nl,get,protocol}
Tuple for answer {nl,protocol,Protocol} Protocol:atom

Example: 

 # Current protocol is static routing protocol
NL,get,protocol
NL,protocol,staticr

Get more information about a specific routing protocol

Format NL,get,protocolinfo,Protocol
Answer NL,protocolinfo,Protocol,\nProperty1 : Value1\n...Property : ValueN\n\n
Tuple for command {nl,get,protocolinfo,Protocol} Protocol atom
Tuple for answer {nl,protocolinfo,Protocol,PropertyList} Protocol: atom
ProtpertyList: list of {Key,Value}
Key: list, Value: list

Example: 

NL,get,protocolinfo,staticr
NL,protocolinfo,
Name		: staticr
Type		: Static Routing
Broadcast	: available
Ack		: false
Type		: Only relay

Set current routing protocol

Format NL,set,protocol,Protocol
Answer NL,protocol,Protocol
NL,protocol,error
Tuple for command {nl,set,protocol,Protocol} Protocol: atom
Tuple for answer {nl,protocol,Protocol}
{nl,protocol,error}

Example: 

 # Set current protocol to flooding routing with ack
NL,set,protocol,sncfloodrack
NL,protocol,ok
 # Current protocol is flooding routing with ack
NL,get,protocol
NL,protocol,sncfloodrack
 # Set current protocol to test routing. Error, such routing does not exist
NL,set,protocol,i
NL,protocol,error

Routing commands

Set current routing

Set current routing. Applicable only with static routing protocol.

Format NL,set,routing,A1→A2,A3→A4,..,default→DefaultAddr
Answer NL,routing,A1→A2,A3→A4,..,default→DefaultAddr
NL,routing,error
Tuple for command {nl,set,routing,RoutingList} RoutingList: list of key-value pairs, key is integer or atom default, value is integer
Tuple for answer {nl,routing,RoutingList}
{nl,routing,error}

Example: 

 # Every message for remote address 2 will be send 2, messages for address 3 to address 2
NL,set,routing,2→2,2→3
NL,routing,2→2,2→3
 # Every message will be send to address 4
NL,set,routing,default→4
NL,routing,default→4
 # Every message for remote address 2 will be send 2, messages for address 3 to address 2.
 # Remaining part to remote  address 4
NL,set,routing,2→2,2→3,default→4
NL,routing,2→2,2→3,default→4
 # Routing can not be sent. Applicable only with static routing protocol.
NL,set,routing,2→2,2→3,default→4
NL,routing,error

Get current routing

Format NL,get,routing
Answer NL,routing,A1->A2,A3->A4,..,default->DefaultAddr
Tuple for command {nl,get,routing}
Tuple for answer {nl,routing,RoutingList} RoutingList: list of key-value pairs, key is integer or atom default, value is integer

Example: 

 # Get current routing.
 # Every message for addresses 2 and 3 will be send to remote address 2.
 # The remaining messages are sent to remote address 4.
NL,get,routing
NL,routing,2→2,2→3,default→4

Neighbour commands

Get current neighbours

Get current neighbours. The list of neighbours is updated after each received message

Format NL,get,neighbours
Answer NL,neighbours,A1:R1:I1:T1,A2:R2:I2:T2,A3:R3:I3:T3...
NL,neighbours,A1,A2,...AN
NL,neighbours,empty
Tuple for command {nl,get,neighbours}
Tuple for answer {nl,neighbours,Neighbours}
{nl,neighbours,empty} 		Neighbours: list of {Addr,Rssi,Integrity,Age}
Addr: integer
Rssi: integer
Integrity: integer
Age: integer

Example: 

 # Get current neighbours. No neighbours were found
NL,get,neighbours
NL,neighbours,empty
 # Get current neighbour. There is information about neighbours with addresses 4,3,2
 # and its channel characteristics
NL,get,neighbours
NL,neighbours,4:-95.0:120.0:14650,3:-95.0:120.0:16455,2:-95.0:120.0:17428

Set current neighbours

Format NL,set,neighbours,A1,A2,A2...
Answer NL,set,neighbours,A1:R1:I1:T1,A2:R2:I2:T2,A3:R3:I3:T3…
NL,set,neighbours,A1,A2,...,AN
NL,neighbours,error
Tuple for command {nl,set,neighbours,AddressList}
{nl,set,neighbours,Neighbours} 		AddresList: list of integers
Neighbours: list of {Addr,Rssi,Integrity,Age}
Addr: integer
Rssi: integer
Integrity: integer
Age: integer
Tuple for answer {nl,neighbours,AddressList}
{nl,neighbours,Neighbours}
{nl,neighbours,error}

Example: 

 # Add neighbours with addresses 2,3, and 4
NL,set,neighbours,2,3,4
NL,neighbours,2,3,4
 # Get current neighbours without channel characteristics. There is no information about these parameters
NL,get,neighbours
NL,get,neighbours,2,3,4

NL,set,neighbours,4:-95.0:120.0:14650,3:-95.0:120.0:16455,2:-95.0:120.0:1742
NL,neighbours,4:-95.0:120.0:14650,3:-95.0:120.0:16455,2:-95.0:120.0:1742

Remove a neighbour from the current neighbour list

Remove a neighbour from the current neighbour list. This updates also the routing table

Format NL,delete,neighbour,Addr
Answer NL,neighbour,ok
Tuple for command {nl,delete,neighbour}
Tuple for answer {nl,neighbour,ok}

Example: 

 # Get current neighbour
NL,get,neighbours
NL,neighbours,4:-95.0:120.0:14650,3:-95.0:120.0:16455,2:-95.0:120.0:17428
 # Get current routing
NL,get,routing
NL,routing,4->4,3->3,2->2
 # Remove  a neighbour with address 4 from the  neighbour list
NL,delete,neighbour,4
NL,neighbour,ok
 # Get current neighbours. No address 4 in the  neihbour list
NL,get,neighbours
NL,neighbours,3:-95.0:120.0:16455,2:-95.0:120.0:17428
 # Get current routing. No address 4 in the routing table
NL,get,routing
NL,routing,3->3,2->2

Time commands

Get monotonic time (Time in milliseconds from the start)

Format NL,get,time,monotonic
Answer NL,time,monotonic,Time
Tuple for command {nl, get, time, monotonic}
Tuple for answer {nl, time, monotonic, Time}

Example: 

NL,get,time,monotonic
NL,time,monotonic,1540456

Statistics commands

Get statistics of all neighbours

Get statistics of all neighbours from start of program till the current time.

Format NL,get,statistics,neighbours
Answer NL,statistics,neighbours,\nRole:relay/source neighbours:Neighbours count:Count total:Total\n...\n\n
NL,statistics,neighbours,empty
NL,statistics,neighbours,error
Tuple for command {nl,get,statistics,neighbours}
Tuple for answer {nl,statistics,neighbours,NeighboursStats}
{nl,statistics,neighbours,empty}
{nl,statistics,neighbours,error} 		NeighboursStats: list of tuples {Role,Neighbours,Count,Total}
Neighbour: integer
Last update: integer (s from start)
Count: integer
Total: integer

Example: 

 # During the whole time, source node got statistics about neighbours with addresses 3, 4 and 2
 # f.e. The neighbour with address 4 was found 5 times of 9 possible
NL,get,statistics,neighbours
NL,statistics,neighbours,
  Neighbour:2 Last update:39538 Count:3 Total:9
  Neighbour:4 Last update:41226 Count:5 Total:9
  Neighbour:3 Last update:41822 Count:1 Total:9

Get statistics of all paths

From start of program till the current time. Applicable for routing protocols of the path finding type.

Format NL,get,statistics, paths
Answer NL,statistics,paths,
Role:relay/source
path:Path
duration:Duration
count:Count
total:Total

NL,statistics,paths,empty
NL,statistics,paths,error
Tuple for command {nl,get,statistics,paths}
Tuple for answer {nl,statistics,paths,Paths}
{nl,statistics,paths,error}
{nl,statistics,paths,empty} 		Paths: list of tuples {Role,Path,Duration,Count,Total}
Role: atom
Path: list of integers
Duration: integer
Count: integer
Total: integer

Example: 

 # Current routing protocol does not have information about the paths
NL,get,statistics,paths
NL,statistics,paths,error
 # Source node with address 1 could build paths 1,2,3 and 1,2,4,3 with durations of 10 and 12 s
 # Total tries 2. 1 time path – 1,2,3. 1 time path – 1,2,4,3
NL,statistics,paths,
 Source Path:1,2,3 Duration:10 Count:1 Total:2
 Source Path:1,2,4,3 Duration:12 Count:1 Total:2

Get statistics of all messages that were sent

From start of program till the current time

Format NL,get,statistics,data
Answer protocols without ack NL,statistics,data,
role:relay/source/destination Hash send_time:Time recv_time:Time src:Src dst:Dst last_ttl:TTL
 Answer protocols with ack NL,statistics,data,
Role:relay/source Hash len:Len duration:Duration state:delivered/failed total:Total dst:Dst hops:Hops

NL,statistics,data,empty
NL,statistics,data,error
Tuple for command {NL,get,statistics,data}
Tuple for answer {NL,statistics,data,DataList}
{NL,statistics,data,empty}
{NL,statistics,data,error} 		Role: atom
Hash: integer
Len: integer
Duration:float
State:atom
Totat: integer
Dst: integer
Hops: integer

Example: 

 # Error, applicable only for routing protocols with ack
NL,get,statistics,data
NL,statistics,data,error

 # No data in statistics
NL,get,statistics,data
NL,statistics,data,empty

NL,get,statistics,data
NL,statistics,data,empty
 Source Data: 0xabde Len:4 Duration:5.6 State:Delivered Total:1 Dst:4 Hops:1
 Source Data: 0x1bdf Len:4 Duration:11.4 State:Delivered Total:1 Dst:4 Hops:2
 Source Data: 0xabdf Len:4 Duration:9.9 State:Delivered Total:1 Dst:4 Hops:2

Clear statistics data

Remove data statitics

Format NL,clear,statistics,data
Answer NL,statistics,data,empty
Tuple for command {nl, clear, statistics, data}
Tuple for answer {nl, statistics, data, empty}

Example: 

NL,clear,statistics,data
NL,statistics,data,empty

State machine commands

Get current state of protocol

Format NL,get,state
Answer NL,state,State(Event)
Tuple for command {nl,get,state}
Tuple for answer {nl,state,{State,Event}} State: string, Event: string

Example: 

 # Current state of finite state machine is wack. Changed to this state running event eps
NL,get,state
NL,state,wack(eps)

Get state transitions backlog

Format NL,get,states
Answer NL,states,
State1(Event1)
...StateN(EventN)
Tuple for command {nl,get,states}
Tuple for answer {nl,states,Transitions} Transitions list of {State,Event}
State: string
Event: string

Example: 

NL,get,states
NL,states,
idle(init)
swv(send_wv)
wack(wait_ack)
wack(rcv_wv)
idle(dst_rcv_ack)
rwv(rcv_wv)
idle(dst_reached)
rwv(rcv_wv)
idle(dst_reached)

Reset state

Reset state. State will be idle

Format NL,reset,state
Answer NL,state,ok
Tuple for command {nl, reset, state}
Tuple for answer {nl, state, ok}

Example: 

NL,get,state
NL,state,wack

NL,reset,state
NL,state,ok

NL,get,state
NL,state,idle

Polling commands / Star topology

Start discovery

Discovery time takes "DiscoveryTotalTime" time in seconds. During this time, a node will try to discover neighbours DiscoveryTotalTime / DiscoveryPeriod times. During discovery time, the channel is busy

Format NL,start,discovery,DiscoveryPeriod,DiscoveryTotalTime
Answer NL,discovery,ok
Asynchronous answer NL,routing,A1->A2,A3->A4,..,default->DefaultAddr
Tuple for command {nl,start,discovery,Period,Total} Period: integer
Total:integer
Tuple for answer {nl,discovery,ok} {nl,routing,RoutingList}
RoutingList: list of key-value pairs
key - integer or atom
value / default value - integer

Example: 

 # Run discovery. After 30 s of discovery time (30/10 – 3 times sending broadcast),
 # we will get asynchronous message. It means the end of discovery procedure
NL,start,discovery,10,30
NL,discovery,ok
NL,routing,3->3,2->2,4->4

Stop discovery

Format NL,stop,discovery
Answer NL,discovery,ok
Tuple for command {nl,stop,discovery}
Tuple for answer {nl,discovery,ok}

Example: 

 # Stop discovery procedure
NL,stop,discovery
NL,discovery,ok

Get discovery parameters

Format NL,get,discovery
Answer NL,discovery,Period,Time
Tuple for command {nl,get,discovery}
Tuple for answer {nl,discovery,Period,Time} Time: integer

Example: 

 # Total discovery time is 30 seconds, discovery period - 10
NL,get,discovery
NL,discovery,10,30

Set polling sequence

Set polling sequence, the sequence is a list of addresses

Format NL,set,polling,Addr1,...,AddrN
NL,set,polling,empty
Answer NL,polling,Addr1,...,AddrN
NL,polling,empty
Tuple for command {nl,set,polling,Seq} Seq: list of integers
Tuple for answer {nl,polling,Seq}

Example: 

 # Set polling sequence 2,3,4
NL,set,polling,2,3,4
NL,polling,2,3,4
NL,set,polling,empty
NL,polling,empty

Get polling sequence

Get polling sequence as a list of addresses

Format NL,get,polling
Answer NL,polling,empty
NL,polling,Addr1,...,AddrN
Tuple for command {nl,get,polling}
Tuple for answer {nl,polling,Seq} Seq: list of integers

Example: 

 # set/get polling sequence
NL,get,polling
NL,polling,empty
NL,set,polling,2,3,4
NL,polling,2,3,4
NL,get,polling
NL,polling,2,3,4

Start polling

Start polling loop Flag [nb] is used to control remotely if we need to get remote burst data or not. If not, the polling loop will get only short PBM messages.

Format NL,start,polling,[b|nb] b - to get burst data from the remote address
nb - to ignore burst data, to send only pbm to update the position
Answer NL,polling,ok
NL,polling,error
Tuple for command {nl,start,polling,Flag} Flag:atom
Tuple for answer {nl,polling,ok}
{nl,polling,error}

Example: 

 # Run polling, polling sequence has to be defined
NL,start,polling,nb
NL,polling,error
 # Set polling sequence
NL,set,polling,2,3,4
NL,polling,2,3,4

NL,start,polling,nb
NL,polling,ok

Stop polling

Format NL,stop,polling
Answer NL,polling,ok
Tuple for command {nl,stop,polling}
Tuple for answer {nl,polling,ok}

Example: 

NL,stop,polling
NL,polling,ok

Flush buffer

Clear all messages are saved in the queue. We have 4 types of messages: sensitive, tolerant, broadcast and alarm. Sensitive and tolerant messages are queued. After the command flush buffer, all queued messages will be removed.

Format NL,flush,buffer
Answer NL,buffer,ok
Tuple for command {nl,flush,buffer}
Tuple for answer {nl,buffer,ok}

Example: 

NL,flush,buffer
NL,buffer,ok

Get buffer

Get the list of not delivered tolerant and sensitive data. Applicable only with polling protocol.

Format NL,get,buffer
Answer NL,buffer,data:Data state:not_delivered dst:Dst type:DataType
NL,buffer,empty 		Data: Binary
State:not_delivered
Dst: integer
DataType : atom - tolerant or sensitive
Tuple for command {nl,get,buffer}
Tuple for answer {nl,buffer,NL}
{nl,buffer,empty}

Example: 

NL,get,buffer
NL,buffer,
data:<<"<<\"->3,4,10,1498138573\">>">> state:not_delivered dst:3 type:tolerant
data:<<"<<\"->2,5,10,1498138583\">>">> state:not_delivered dst:2 type:sensitive

Error handling

In case of command parse error {NL,error} can be generated.

Answer NL,error
Tuple for answer {nl,error}
Add a custom footer
Add a custom sidebar
Clone this wiki locally