Widom-api

Version 15 (Nuno -, 03/07/2007 07:31 pm)

1 6 Nuno -
= Nano-RK WiDom API =
2 1 Nuno -
3 1 Nuno -
 * '''int8_t wd_init(RF_RX_INFO *pRRI, uint8_t channel)'''
4 11 Nuno -
    * Initializes the radio and protocol. Initializes CC2420 for radio communication via the basic RF library functions. Turns on the voltage regulator, resets the CC2420 and turns on the crystal oscillator. Note that the crystal oscillator will remain on (forever). The pointer (''pRRI'') to RF_RX_INFO data structure is to be used during the first packet reception. The structure can be switched upon packet reception. The ''channel'' defines the RF channel to be used (11 = 2405 MHz to 26 = 2480 MHz). This function '''must be called from inside a task, and never before ''nrk_start()'''''.
5 1 Nuno -
6 2 Nuno -
 * '''uint8_t wd_tx_packet(RF_TX_INFO *pRTI, uint16_t priority)'''
7 2 Nuno -
    * This passes a packet to be sent.  WiDom will not queue packets, so calling this function from multiple tasks concurrently will return an error code. A value of 1 is returned if the packet was accepted. -1 is returned upon failure. This call will return immediately, but the packet will eventually be later. The argument ''priority'' indicates the priority of the message.
8 1 Nuno -
9 2 Nuno -
 * '''uint8_t wd_wait_tx_packet(RF_TX_INFO *pRTI, uint16_t priority)'''
10 2 Nuno -
    * This passes a packet to be sent and waits until the end transmission.  WiDom will not queue packets, so calling this function from multiple tasks concurrently will return an error code. A value of 1 is returned if the packet was transmitted. -1 is returned upon failure. This call will return after the packet was transmitted or a failure occurs. The argument ''priority'' indicates the priority of the message.
11 1 Nuno -
12 2 Nuno -
 * '''int8_t wd_check_rx_status()'''
13 2 Nuno -
    * This function checks if a packet was received. Returns a value >=0 if there is a packet received and buffered.
14 1 Nuno -
15 2 Nuno -
 * '''RF_RX_INFO *wd_get_rx_packet()'''
16 2 Nuno -
    * This function returns pointer to received packet info. Returns a value !=NULL if there is a packet received and buffered.
17 1 Nuno -
18 2 Nuno -
 * '''int8_t wd_release_rx_packet()'''
19 3 Nuno -
    * Releases the reception buffer. ''It is necessary to call this function whenever a new packet is received''. Otherwise, ''WiDom will not enqeue newly received packets''.
20 1 Nuno -
21 2 Nuno -
 * '''int8_t wd_wait_until_tx_packet()'''
22 2 Nuno -
    * Blocks until next packet transmission.
23 1 Nuno -
24 2 Nuno -
 * '''int8_t wd_wait_until_rx_packet()'''
25 2 Nuno -
    * Blocks until next packet reception.
26 1 Nuno -
27 3 Nuno -
----
28 1 Nuno -
29 3 Nuno -
== Using WiDom ==
30 1 Nuno -
31 3 Nuno -
You must start by including widom and define transmit and receive buffers.
32 2 Nuno -
33 1 Nuno -
{{{
34 3 Nuno -
#include <widom.h>
35 3 Nuno -
#include <widom_rf.h>
36 3 Nuno -
RF_TX_INFO rfTxInfo;
37 3 Nuno -
RF_RX_INFO rfRxInfo;
38 3 Nuno -
uint8_t tx_buf[RF_MAX_PAYLOAD_SIZE];
39 3 Nuno -
uint8_t rx_buf[RF_MAX_PAYLOAD_SIZE];
40 1 Nuno -
}}}
41 1 Nuno -
42 1 Nuno -
43 3 Nuno -
'''Initialization'''
44 1 Nuno -
45 1 Nuno -
46 15 Nuno -
Function '''wd_init()''' initializes the radio and protocol. This function must be called from inside a task, and never before '''nrk_start()'''.
47 1 Nuno -
48 1 Nuno -
{{{
49 3 Nuno -
rfRxInfo.pPayload = rx_buf;
50 3 Nuno -
rfRxInfo.max_length = RF_MAX_PAYLOAD_SIZE;
51 3 Nuno -
wd_init (&rfRxInfo, WD_CHANNEL);
52 1 Nuno -
53 1 Nuno -
}}}
54 1 Nuno -
55 1 Nuno -
56 4 Nuno -
'''Sending a Packet'''
57 4 Nuno -
58 4 Nuno -
59 1 Nuno -
Sending a packet is done by either either function '''wd_tx_packet()''' or''' wd_tx_wait_packet()'''. While function
60 1 Nuno -
'''wd_tx_packet()''' just signals to the protocol that a new packet was enqued, '''wd_wait_tx_packet()''' signals
61 1 Nuno -
the new packet and blocks until it is sent. These two functions accept as arguments a ''RF_TX_INFO'' data
62 1 Nuno -
structure and the priority of the message.
63 1 Nuno -
{{{
64 1 Nuno -
// fill packet buffer with data ...
65 1 Nuno -
for (i=0; i<DATA_LENGHT; i++) tx_buf[i]=data[
66 1 Nuno -
rfTxInfo.pPayload=tx_buf;
67 1 Nuno -
wd_wait_tx_packet(&rfTxInfo, MY_MSG_PRIO);
68 1 Nuno -
}}}
69 1 Nuno -
70 1 Nuno -
71 1 Nuno -
''or''
72 1 Nuno -
73 1 Nuno -
74 1 Nuno -
{{{
75 1 Nuno -
// fill packet buffer with data ...
76 1 Nuno -
for (i=0; i<DATA_LENGHT; i++) tx_buf[i]=data[i];
77 1 Nuno -
rfTxInfo.pPayload=tx_buf;
78 1 Nuno -
wd_tx_packet(&rfTxInfo, MY_PRIO);
79 8 Nuno -
wd_wait_until_tx_packet();
80 1 Nuno -
}}}
81 8 Nuno -
82 8 Nuno -
One does not need to wait until the packet transmission is finished, and thus the call to '''wd_wait_until_tx_packet()''' is not mandatory;
83 1 Nuno -
84 1 Nuno -
85 1 Nuno -
'''Receiving a Packet'''
86 1 Nuno -
87 1 Nuno -
88 1 Nuno -
To receive a packet, call '''wd_wait_until_rx_packet()'''. And do not forget to release the reception buffer with '''wd_release_rx_packet()'''.
89 1 Nuno -
{{{
90 1 Nuno -
wd_wait_until_rx_packet();
91 1 Nuno -
// get data from packet ...
92 1 Nuno -
for (i=0; i<rfRxInfo.length; i++) putchar (rfRxInfo.pPayload[i]);
93 1 Nuno -
// release buffer
94 1 Nuno -
wd_release_rx_packet();
95 7 Nuno -
}}}
96 7 Nuno -
97 7 Nuno -
98 12 Nuno -
99 12 Nuno -
== Advanced issues ==
100 12 Nuno -
101 12 Nuno -
102 12 Nuno -
'''Choosing Protocol Version'''
103 12 Nuno -
104 12 Nuno -
There are three diferent versions of WiDom implemented in nano-RK:[[BR]]
105 12 Nuno -
106 14 Nuno -
  * Widom Single Broadcast Domain (SBD) using the CC2420 to send priority bits and data messages (WD_SBD_CC2420 - This version works in both the FireFly and MicaZ platforms);
107 14 Nuno -
  * Widom Single Broadcast Domain (SBD) using the CC2420 to send and receive data messages and the RFLINX OOK add-on board, a.k.a. wings board for bit arbitration (WD_SBD_RFLNX - This version works only in the FireFly platform);
108 14 Nuno -
  * Widom Multiple Broadcast Domains (MBD) that relies on an external synchronization device (WD_MBD_EXT_SYNC - This version works only in the FireFly platform).
109 12 Nuno -
110 12 Nuno -
 The version that is compiled is chosen in '''widom.h'''.
111 12 Nuno -
112 12 Nuno -
{{{
113 13 Nuno -
// define mode/version of the protocol (WD_SBD_CC2420, WD_SBD_RFLNX, WD_MBD_EXT_SYNC)
114 12 Nuno -
#define WD_VERSION WD_SBD_CC2420
115 12 Nuno -
}}}
116 12 Nuno -
117 12 Nuno -
118 12 Nuno -
119 7 Nuno -
'''Protocol Parameters'''
120 12 Nuno -
121 7 Nuno -
122 7 Nuno -
123 7 Nuno -
The protocol parameters can be set in '''widom.h'''. '''Usually, there is no need to change this'''.
124 7 Nuno -
The number of priority bits used is defined by ''NPRIOBITS''.
125 7 Nuno -
The time out parameters (''E'', ''G'', ''ETG'') can be set in micro-seconds units. We also can define the maximum
126 7 Nuno -
packet duration allowed.
127 9 Nuno -
The default parameters are based on the the following parameters: ''ε'' = 10−5, CLK = 1/8 × 10−6,
128 7 Nuno -
''L'' = 5us, ''α'' = 1us, ''TFCS'' = 256us and ''SYNC_ERROR'' = 50us. This gives the timeouts ''F'' = 320us,
129 7 Nuno -
''G'' = 58us and ''ETG'' = 59us.
130 7 Nuno -
131 7 Nuno -
{{{
132 7 Nuno -
// num of priorities
133 7 Nuno -
#define NPRIOBITS 3 // number of priority bits
134 7 Nuno -
// timeouts interval constants (in us)
135 7 Nuno -
#define H_us 320 // duration of a pulse of a carrier
136 7 Nuno -
#define G_us 58 // "guarding" time between bits
137 7 Nuno -
#define ETG_us 59 // "guarding" time after the tournament
138 7 Nuno -
#define CMSG_us WD_MAX_MSG_LEN_us // max time to tx our messages
139 7 Nuno -
}}}
140 7 Nuno -
141 7 Nuno -
The parameters related to the synchronization are the the following. The amount of time before
142 7 Nuno -
receiving the synchronization packet the node must start polling for it is defined by three parameters
143 7 Nuno -
(''WD_MAX_BLOCKING_TIME'', ''WD_SYNC_PULSE_RX_SWX and WD_SYNC_WITH_MASTER_MAX_ERROR).
144 7 Nuno -
The synchronization period is automatically defined by WD_SYNC_PERIOD as a function of the duration of
145 7 Nuno -
the tournament and message transmission. 
146 7 Nuno -
147 7 Nuno -
{{{
148 7 Nuno -
// these three parameters define how long we wake up before the synchronization
149 7 Nuno -
#define WD_MAX_BLOCKING_TIME_us 150 // maximum blocking widom may experience
150 7 Nuno -
#define WD_SYNC_PULSE_RX_SWX_us 256 // time to switch to rx and lock on to the preamble
151 7 Nuno -
#define WD_SYNC_WITH_MASTER_MAX_ERROR 400 // maximum difference with synch master
152 4 Nuno -
}}}