nanosocket api 1 - texas instrumentsprocessors.wiki.ti.com/images/2/29/nanosocket_api_1.0.pdf ·...

NanoStack 2.0 library for cc430

NanoSocket API 1.0(EM430f5137RF900 REV 3.2)

Customer Confidential ©2011 Sensinode Ltd. 1/24


VersionVersion Date By Comment

V0.9 25.01.2011 JP Sensinode internal change log, ask JoniV0.91 14.02.2011 JP Removed NAPSocket prefixV0.92 01/03/11 JP Interium release documentationV0.99 3.11 JP RC1 proof check, convert into cc430 library documentationV1.0 8.4 JP Final documentation

Table of Contents

1 Introduction....................................................................................................................................................42 Goals and objectives......................................................................................................................................4

2.1 Architectural description........................................................................................................................53 Interface description......................................................................................................................................6

3.1 Command interface................................................................................................................................63.1.1 library_init......................................................................................................................................63.1.2 net_start..........................................................................................................................................63.1.3 net_stop..........................................................................................................................................73.1.4 net_address_get..............................................................................................................................73.1.5 net_get_connection_information....................................................................................................8

3.2 Data structures and enumerations..........................................................................................................83.2.1 event_t............................................................................................................................................83.2.2 s_event............................................................................................................................................93.2.3 s_event..........................................................................................................................................103.2.4 net_mode......................................................................................................................................113.2.5 address_type.................................................................................................................................113.2.6 protocol_t......................................................................................................................................123.2.7 net_value_t...................................................................................................................................123.2.8 ns_error_t......................................................................................................................................133.2.9 error_t...........................................................................................................................................133.2.10 address_struct.............................................................................................................................143.2.11 rf_info_t......................................................................................................................................143.2.12 net_connection_information.......................................................................................................153.2.13 Event specific data structures.....................................................................................................153.2.14 Constants, definitions and functions..........................................................................................15

3.3 Socket interface....................................................................................................................................183.3.1 socket_open..................................................................................................................................183.3.2 socket_bind...................................................................................................................................183.3.3 socket_recvfrom...........................................................................................................................193.3.4 socket_sendto...............................................................................................................................203.3.5 socket_read_info..........................................................................................................................20



3.4 Debug interface....................................................................................................................................213.4.1 debug_hex....................................................................................................................................213.4.2 debug_int......................................................................................................................................213.4.3 debug_get.....................................................................................................................................223.4.4 debug............................................................................................................................................22

3.5 Timers and timer events.......................................................................................................................223.5.1 timer_sys_event............................................................................................................................223.5.2 timer_sys_event_cancel................................................................................................................23



1 Introduction

This document describes a NanoStack 2.0 library for TI CC430.

2 Goals and objectives

The user is able to use configuration commands via a simple command interface. A socket

interface provides transmissions of a 6LoWPAN messages. The library contains a sophisticated

operating system called NanoStack 2.0, which means that user doesn't need to implement drivers

and operating system for the chosen platform.



2.1 Architectural description

This subsection introduces an architectural overview of the library. Figure 1 illustrates the library

structure.

In Figure 1, the Command interface is a built in module of the NanoStack 2.0 library which

handles all configuration requests and replies. The Socket interface provides usage of a

6LoWPAN data messages. Events are used to inform the user of incoming data packets,

command replies or other NanoStack 2.0 specific events.


Figure 1: NanoStack 2.0 library architecture.


3 Interface description

This Chapter contains details of each interface function and data type.

3.1 Command interface

User provided tasklet_main() acts as an event parser. tasklet_main() is called through the function

pointer from the library each time when there is a data in a socket queue or when a NanoStack

2.0 event is received. It is user responsibility to parse events.

3.1.1 library_init

(Signed) char library_init(void);

library_init() is used to initialize the library. This function call is used by the user application in the

initialization phase. It initializes the library internal structures.

Parameters: Descriptionevent_handler A function pointer to the user provided event

handler function.Return values: Description0 Initialization done

3.1.2 net_start

(Signed) char net_start(net_mode net_mode);

net_start() function call starts the radio module. All configuration calls should be executed before

net_start().



Parameters: Descriptionnet_mode Requested network modeValid values: NW_INFRA

NW_INFRA_AES

Network mode

Encrypted network mode (Only used after net_key_set function call)

Return values: Description0 No errors-1 Parameter error: Invalid value as a parameter-2 Mode error: No AES key set

3.1.3 net_stop

Void net_stop(void);

net_stop() function call disconnects a node from a network and enables sleep mode (low power

mode 3 for CC430) if allowed.

3.1.4 net_address_get

(Signed) char net_address_get(address_type addr_id, address_struct *address);

net_address_get() function call requests a defined type of address of the Network Processor.

Parameters: Descriptionaddress A pointer to user allocated address structureaddr_type Requested address typeValid values: NET_ADDR_EUID 8 byte unique ID

Return values: Description



0 No errors-1 Parameter error: Invalid value as a parameter

The reply is copied into a given address_struct.

3.1.5 net_get_connection_information

(Signed) char net_get_connection_information(net_connection_information *info_ptr);

net_get_connection_information() function call requests information about the network

connection.

Parameters: Descriptioninfo_ptr A pointer to user allocated

net_connection_information structureReturn values: Description0 Successful request, reply copied into info_ptr-1 info_ptr is a null pointer

3.1.6 net_key_set

(Signed) char net_key_set(uint8_t *new_key);

net_key_set() function call is used to set 16 byte AES key to encode 802.15.4e frame payloads.

Parameters: Descriptionnew_key A pointer to user defined keyReturn values: Description0 Success-1 new_key null pointer



3.2 Data structures and enumerations

3.2.1 event_t

Following type definition defines the used event structure.

Typedef struct event_t

{

s_tasklet receiver;

s_tasklet sender;

s_event event;

}event_t;

Parameters: Descriptionreceiver Identifying a receiving taskletsender Identifying a sender componentevent Identifying an event type

3.2.2 s_event

Following enumeration enumerates possible event types.

Typedef enum s_event

{

EV_INIT,

EV_UART0,

EV_UART1,

EV_SOCKET,



EV_PROFILE,

EV_TIMER,

EV_RF,

EV_MAX

}s_event;

EV_INIT – An event which is generated when the NanoStack 2.0 library is initialized.

EV_UARTx – An event to inform if data is received into UART buffer.

EV_SOCKET – An event to inform if a data packet is received into a socket buffer (e.g. UDP)

EV_PROFILE – An event for the library testing purposes (not used)

EV_TIMER – A timer event is an event which is triggered after a defined period of time if a timer

event is requested.

EV_RF – a radio event (not used)

EV_MAX – an event value for the NanoStack 2.0 library internal usage

3.2.3 s_event

Following enumeration defines possible event_t.receiver / event_t.sender types.

Typedef enum s_tasklet

{

SYSTEM,

SYSTEM_TIMER,

SYSTEM_MAC,

TL_PROTOCOL,

TL_MAIN,

TL_MAX



}s_tasklet;

SYSTEM – Indicates a NanoStack 2.0 core

SYSTEM_TIMER – Indicates a NanoStack 2.0 timer

SYSTEM_MAC - Indicates a NanoStack 2.0 compliant MAC layer (not used)

TL_PROTOCOL – Indicates a NanoStack 2.0 internal tasklet

TL_MAIN – Indicates a NanoStack 2.0 user application tasklet_main-tasklet

TL_MAX – Internally used test value

3.2.4 net_mode

net_mode enumerates different operation modes.

Typedef enum net_mode

{

NW_INFRA = 0,

NW_INFRA_AES = 1,

NW_SHUTDOWN = 2,

NW_UNKNOWN = 255

};

NW_INFRA – An active mode with no encryption

NW_INFRA_AES – An active mode with an AES CCM* encoded 802.15.4e frames

NW_SHUTDOWN – An inactive mode where a node is disconnected from a network and tries to

save power.

NW_UNKNOWN – An unknown mode indicator (not used)



If NW_INFRA mode is set, any secured 802.15.4e frames are dropped silently. If

NW_INFRA_AES mode is set, any unsecured 802.15.4e frames are dropped silently.

3.2.5 address_type

address_type enumerates different address types.

Typedef enum address_type

{

NET_ADDR_NONE = 0,

NET_ADDR_SHORT = 1,

NET_ADDR_EUID = 2,

NET_ADDR_IPV6 = 3,

NEW_ADDR_MULTICAST=4,

NET_ADDR_UNKNOWN = 255

}address_type;

Address type NET_ADDR_MULTICAST allows user to send a UDP packet to all neighbors in

range. (So called multicast group 2) (no need to type destination address)

3.2.6 protocol_t

protocol_t enumerates different protocol types to be used with the library.

Typedef enum protocol_t

{

PROTOCOL_NONE = 0,

PROTOCOL_UDP = 48,



PROTOCOL_UNKNOWN = 255

}protocol_t;

Protocol values should range from 0 to 255. Any other values than enumerated above are

reserved for future use.

3.2.7 net_value_t

net_value_t is an unused enumeration.

Typedef enum net_value_t

{

}net_value_t;.

3.2.8 ns_error_t

ns_error_t is an unused data structure.

Typedef enum ns_error_t

{

unsigned char error_id;

}ns_error_t;.

3.2.9 error_t

error_t is an unused enumeration.

Typedef enum error_t

{Customer Confidential ©2011 Sensinode Ltd. 13/24


eOK = 0,

eFALSE = 1,

eBUSY = 2,

eSYSTEM

}error_t;.

eOK – No errors

eFALSE – Failure return value

eBUSY – Requested resource is busy

eSYSTEM – Unknown or internal error type

3.2.10 address_struct

address_struct defines format of data structure which contains addressing information.

Typedef struct address_struct

{

address_type addr_type

unsigned char address[16];

unsigned short int port;

} address_struct;

The port is especially used for UDP protocol where source and destination ports are needed.

3.2.11 rf_info_t

rf_info_t defines format of data structure which contains addressing information.

Typedef struct rf_info_t



{

unsigned short int length;

signed char RSSI_value;

unsigned char LQI_value;

} rf_info_t;

3.2.12 net_connection_information

Typedef struct net_connection_information

{

unsigned char status;

unsigned char HWaddr[8];

unsigned char inet6_addr[16];

unsigned char next_hop[16];

unsigned char inet6_gateway[16];

unsigned char hop;

}net_connection_information;

HWaddr – A 8 byte unique address of the device

inet6_addr – A 16 byte IPv6 address of the device

next_hop – A 16 byte IPv6 address of the RPL parent (next hop node)

inet6_gateway – A 16 byte IPv6 address of the access point (NanoRouter)

hop – A current hop (e.g. 1 if node is next to an access point)

3.2.13 Event specific data structures



3.2.14 Constants, definitions and functions

Following table introduces some constants which are used for initialization of the library. If the user

doesn't define these variables, following default values are used.

Type Default Description#define SOCKETS_MAX 20 Defines a maximum amount of open

sockets.#define SOCKET_RX_LIMIT 5 Defines a length of a buffer queue for

each open socket. (every slot needs to

be read when an EV_SOCKET event is

received.Unsigned char

8 byte unique address MSB

byte starting from 0xff70

-- 8 byte unique device address

#define DEBUG_SPEED 115200 Debug interface fixed baud rate#define TASKLETS_MAX 2 The maximum amount of active tasklets#define EVENT_MAX 40 The maximum amount of queued event_t

events#define TIMER_SYS_MAX 20 The maximum amount of concurrent

active timers#define NULL (void *)0 Null definition#define pl_int_disable() – A macro to call IAR global interrupt

disable#define pl_int_enable() – A macro to call IAR global interrupt

enable#define PL_LARGE – Unused definition#define PL_REENTRANT – Unused definition#define __code – Unused definitiontypedef Unsigned char prog_uint8_ttypedef Signed char prog_int8_ttypedef Unsigned short int prog_uint16_

ttypedef Signed short int prog_int16_ttypedef Unsigned long int prog_uint32_

t



typedef Signed long int prog_int32_ttypedef Unsigned long int uint32_ttypedef Signed long int int32_ttypedef Unsigned short int uint16_ttypedef Signed short int int16_ttypedef Unsigned char uint8_ttypedef Signed char int8_textern Void

pl_cancel_wakeup_request(v

oid)

-- Library internal function to cancel

wakeup requests

extern Void

pl_request_wakeup(void)

-- Library internal function to request

wakeupextern uint8_t

pl_check_wakeup(void)

– Library internal function to check if

wakeup is requested#define EV_DEBUG EV_UARTx Defines used uart event into user

application simpleextern Void debug_hw_init(void) -- Library internal function to initialize

debug hardwareextern Void debug_init(void) – Library internal function to initialize

debug softwareextern Void debug_close(void) -- Library internal function to disable debug

interfacesextern Void debug_send(__code

const uint8_t *str)

– Library internal function to handle user

requestsextern Void

debug_send_const(__code

const uint8_t *str)

-- Library internal function to handler user

requests

extern Void debug_terminal(void) – Library internal function (not used)extern error_t event_receive(event_t

*event, uint32_t time)

-- Library internal function (not used)

-- error_t

event_system_alloc(s_event

event_id)

-- Library internal function to initialize the

library internal data structures

extern __monitor void

rf_rx_callback(void)

– Library internal function to handle RF RX

operations



extern __monitor void

rf_tx_callback(void)

– Library internal function to handle RF TX

operations#define DMA_FUNC_0 rf_rx_callbac

k

Library internal macros

#define DMA_FUNC_1 rf_tx_callbac

k

Library internal macros

#define PRODUCT_ID 0xde,

0xad,0xbe,0

xef

Not used

Extern Void

DISABLE_AUTOMATIC_LED

S(void)

-- This function call disabled automatic led

usage (disables LEDx functions)

3.3 Socket interface

The Socket interface provides the user an easy-to-use access to send and receive an application

specific data.

3.3.1 socket_open

(Signed) char socket_open(protocol_t protocol);

socket_open() is used to initialize a socket for a communication.

Parameters: Descriptionprotocol Defined protocol type.Valid values: PROTOCOL_UDP Protocol type to be used with socket.

Return values: Description0 or positive A socket identifier (Socket ID); used as a

reference in future calls-1 No free sockets



3.3.2 socket_bind

(Signed) char socket_bind(char socket, unsigned short int identifier);

This function call is used to assign a port number to a socket. Only one port can be assigned to

one socket.

Parameters: Descriptionsocket Socket ID. Return value of the socket_open()

call.identifier Protocol multiplexing ID, i.e. port number.Return values: Description0 Success-1 Bind already done.-2 Reassign port.-3 Socket ID error. Socket not open?

3.3.3 socket_recvfrom

(Signed) short int socket_recvfrom(char socket, address_struct *address, unsigned char *buffer, unsigned short int length);

socket_recvfrom() is used to read received data from the socket.


call.address Address pointer, source address will be stored

here.buffer Data buffer pointer



max_length Size of data bufferReturn values: Description0 or positive Length of read data-5 Socket data was null pointer?-1 Non-bind socket-2 Provided buffer too short (according to length

parameter), read data again into longer buffer.

(if user doesn't read data from the socket, data

is left into queues and may cause RAM

exhausting-4 Address type unknown, socket data is deleted

by the library-3 Passed buffer error (null pointer). Read data

again into a valid buffer. (if user doesn't read

data from the socket, data is left into queues

and may cause RAM exhausting

3.3.4 socket_sendto

(Signed) char socket_sendto(char socket, address_struct *address, unsigned char *buffer, unsigned short int length);

socket_sendto() is used to send data via the socket.

Parameters: Descriptionsocket Socket ID. Return value of the socket open()

call.address Address pointer, source address will be stored

here.buffer Data buffer pointerlength Size of data buffer



Return values: Description0 Data accepted by the library.-1 Unknown socket ID or socket not open or bind-2 Parameter error, buffer was null pointer?-3 Unknown address type defined in address

structure

3.3.5 socket_read_info

Unsigned char socket_read_info(char socket, rf_info_t *info);

socket_read_info() is used to read additional info (such as signal level information) of the last

data packet read by socket_recvfrom().


call.Info A structure to where information is copied toReturn values: Description0 Success-1 Socket not bind properly-2 Info was null pointer

3.4 Debug interface

This subsection introduces a debug interface to be used with the library. The library initializes the

debug interface if a NS_DEBUG compiler flag is defined (#define).

3.4.1 debug_hex

Void debug_hex(Signed short int x);

debug_hex() function call is used to send a value x to UART/serial port in a hexadecimal format.



E.g. 16 would be sent as 0x10. Parameter is given in 16 bit signed form but actually makes use

only of values from 0 to 255 (0x00 to 0xff)

Parameters: Descriptionx A parameter to be printed out in hexadecimal

format

3.4.2 debug_int

Void debug_int(Signed short int x);

debug_int() function call is used to send a signed 16 bit value x to uart in as it is. The function

generates '-' (minus) if the value is negative.

Parameters: Descriptionx A parameter to be printed out in a signed 16 bit

decimal format

3.4.3 debug_get

Signed short int debug_get(void);

debug_get() function call is used to read a byte out from RX queue of the UART driver. Used

together with EV_UARTx events. If EV_UARTx event is received, this function can be used to

receive a byte which caused an event.

Return: Description0 or positive value A received byte-1 Queues were empty

3.4.4 debug

Void debug(Unsigned char *str);

debug() function call is used to send a string to UART as a string. E.g. can be used to transmit a

string “hello world”.

Parameters: Descriptionstr A pointer to a string to be sent must contain 0



as an end marker. (\0)

3.5 Timers and timer events

3.5.1 timer_sys_event

__monitor void timer_sys_event(uint8_t message, uint16_t time, uint8_t mode);

timer_sys_event() function call is used to request a timer event (event_t: s_event EV_TIMER, sender tasklet s_tasklet SYSTEM, receiver tasklet s_tasklet TL_MAIN). This function is a non-

blocking function. __monitor definition is an IAR macro which prevents all interrupts during this

function. This function generates always an event even if one or more events with a same timer ID

were requested. Therefore it is recommended to use always a timer_sys_event_cancel() function

call before this function call.

The event is triggered only once. If periodic timer events are required, one may call this function

again after it has triggered an event. This way the event is requested each time the event is

triggered causing an event with a certain interval defined by the time parameter.

Parameter: Descriptionmessage An ID to identify a timer (timer ID, for each

different timer unique ID must be used)time Timeout when the timer event should trigger.

(milliseconds). Since timer events are queued,

scheduling might prevent exact timings.

NanoStack 2.0 timer driver works in 10 ms slots

and therefore may prevent an exact use and will

restrict the minimum timeout to be at least 20

ms.mode NanoStack 2.0 internal parameter. Must be

always 1 for user application. Any other value

may cause hang ups as timer events are

triggered into wrong tasklets.



3.5.2 timer_sys_event_cancel

__monitor void timer_sys_event_cancel(uint8_t message, uint8_t mode);

timer_sys_event_cancel() function call is used to request a timer event to be cancelled. This

function is non-blocking function to be used within the user application. __monitor definition is an

IAR macro which prevents all interrupts during this function.

Parameter: Descriptionmessage An ID to identify a timer (timer ID, for each

different timer unique ID must be used)mode NanoStack 2.0 internal parameter. Must be

always 1 for user application.

NOTE: It is good practice to always call timer_sys_event_cancel() function before calling

timer_sys_event to avoid timer event flood in case of misuse.


nanosocket api 1 - texas instrumentsprocessors.wiki.ti.com/images/2/29/nanosocket_api_1.0.pdf ·...

Documents