Contiki-NG
radio.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2005, Swedish Institute of Computer Science.
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  * 1. Redistributions of source code must retain the above copyright
9  * notice, this list of conditions and the following disclaimer.
10  * 2. Redistributions in binary form must reproduce the above copyright
11  * notice, this list of conditions and the following disclaimer in the
12  * documentation and/or other materials provided with the distribution.
13  * 3. Neither the name of the Institute nor the names of its contributors
14  * may be used to endorse or promote products derived from this software
15  * without specific prior written permission.
16  *
17  * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
18  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20  * ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
21  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27  * SUCH DAMAGE.
28  *
29  * This file is part of the Contiki operating system.
30  *
31  */
32 
33 /**
34  * \file
35  * Header file for the radio API
36  * \author
37  * Adam Dunkels <adam@sics.se>
38  * Joakim Eriksson <joakime@sics.se>
39  * Niclas Finne <nfi@sics.se>
40  * Nicolas Tsiftes <nvt@sics.se>
41  */
42 
43 /**
44  * \addtogroup dev
45  * @{
46  */
47 
48 /**
49  * \defgroup radio Radio API
50  *
51  * The radio API module defines a set of functions that a radio device
52  * driver must implement.
53  *
54  * @{
55  */
56 
57 #ifndef RADIO_H_
58 #define RADIO_H_
59 
60 #include <stddef.h>
61 
62 /**
63  * Each radio has a set of parameters that designate the current
64  * configuration and state of the radio. Parameters can either have
65  * values of type radio_value_t, or, when this type is insufficient, a
66  * generic object that is specified by a memory pointer and the size
67  * of the object.
68  *
69  * The radio_value_t type is set to an integer type that can hold most
70  * values used to configure the radio, and is therefore the most
71  * common type used for a parameter. Certain parameters require
72  * objects of a considerably larger size than radio_value_t, however,
73  * and in these cases the documentation below for the parameter will
74  * indicate this.
75  *
76  * All radio parameters that can vary during runtime are prefixed by
77  * "RADIO_PARAM", whereas those "parameters" that are guaranteed to
78  * remain immutable are prefixed by "RADIO_CONST". Each mutable
79  * parameter has a set of valid parameter values. When attempting to
80  * set a parameter to an invalid value, the radio will return
81  * RADIO_RESULT_INVALID_VALUE.
82  *
83  * Some radios support only a subset of the defined radio parameters.
84  * When trying to set or get such an unsupported parameter, the radio
85  * will return RADIO_RESULT_NOT_SUPPORTED.
86  */
87 
88 typedef int radio_value_t;
89 typedef unsigned radio_param_t;
90 
91 enum {
92 
93  /* Radio power mode determines if the radio is on
94  (RADIO_POWER_MODE_ON) or off (RADIO_POWER_MODE_OFF). */
95  RADIO_PARAM_POWER_MODE,
96 
97  /*
98  * Channel used for radio communication. The channel depends on the
99  * communication standard used by the radio. The values can range
100  * from RADIO_CONST_CHANNEL_MIN to RADIO_CONST_CHANNEL_MAX.
101  */
102  RADIO_PARAM_CHANNEL,
103 
104  /* Personal area network identifier, which is used by the address filter. */
105  RADIO_PARAM_PAN_ID,
106 
107  /* Short address (16 bits) for the radio, which is used by the address
108  filter. */
109  RADIO_PARAM_16BIT_ADDR,
110 
111  /*
112  * Radio receiver mode determines if the radio has address filter
113  * (RADIO_RX_MODE_ADDRESS_FILTER) and auto-ACK (RADIO_RX_MODE_AUTOACK)
114  * enabled. This parameter is set as a bit mask.
115  */
116  RADIO_PARAM_RX_MODE,
117 
118  /*
119  * Radio transmission mode determines if the radio has send on CCA
120  * (RADIO_TX_MODE_SEND_ON_CCA) enabled or not. This parameter is set
121  * as a bit mask.
122  */
123  RADIO_PARAM_TX_MODE,
124 
125  /*
126  * Transmission power in dBm. The values can range from
127  * RADIO_CONST_TXPOWER_MIN to RADIO_CONST_TXPOWER_MAX.
128  *
129  * Some radios restrict the available values to a subset of this
130  * range. If an unavailable TXPOWER value is requested to be set,
131  * the radio may select another TXPOWER close to the requested
132  * one. When getting the value of this parameter, the actual value
133  * used by the radio will be returned.
134  */
135  RADIO_PARAM_TXPOWER,
136 
137  /*
138  * Clear channel assessment threshold in dBm. This threshold
139  * determines the minimum RSSI level at which the radio will assume
140  * that there is a packet in the air.
141  *
142  * The CCA threshold must be set to a level above the noise floor of
143  * the deployment. Otherwise mechanisms such as send-on-CCA and
144  * low-power-listening duty cycling protocols may not work
145  * correctly. Hence, the default value of the system may not be
146  * optimal for any given deployment.
147  */
148  RADIO_PARAM_CCA_THRESHOLD,
149 
150  /* Received signal strength indicator in dBm. */
151  RADIO_PARAM_RSSI,
152 
153  /* RSSI of the last received packet */
154  RADIO_PARAM_LAST_RSSI,
155 
156  /* Link quality of the last received packet */
157  RADIO_PARAM_LAST_LINK_QUALITY,
158 
159  /*
160  * Long (64 bits) address for the radio, which is used by the address filter.
161  * The address is specified in network byte order.
162  *
163  * Because this parameter value is larger than what fits in radio_value_t,
164  * it needs to be used with radio.get_object()/set_object().
165  */
166  RADIO_PARAM_64BIT_ADDR,
167 
168  /* Last packet timestamp, of type rtimer_clock_t.
169  * Because this parameter value mat be larger than what fits in radio_value_t,
170  * it needs to be used with radio.get_object()/set_object(). */
171  RADIO_PARAM_LAST_PACKET_TIMESTAMP,
172 
173  /* Constants (read only) */
174 
175  /* The lowest radio channel. */
176  RADIO_CONST_CHANNEL_MIN,
177  /* The highest radio channel. */
178  RADIO_CONST_CHANNEL_MAX,
179 
180  /* The minimum transmission power in dBm. */
181  RADIO_CONST_TXPOWER_MIN,
182  /* The maximum transmission power in dBm. */
183  RADIO_CONST_TXPOWER_MAX
184 };
185 
186 /* Radio power modes */
187 enum {
188  RADIO_POWER_MODE_OFF,
189  RADIO_POWER_MODE_ON
190 };
191 
192 /**
193  * The radio reception mode controls address filtering and automatic
194  * transmission of acknowledgements in the radio (if such operations
195  * are supported by the radio). A single parameter is used to allow
196  * setting these features simultaneously as an atomic operation.
197  *
198  * To enable both address filter and transmissions of automatic
199  * acknowledgments:
200  *
201  * NETSTACK_RADIO.set_value(RADIO_PARAM_RX_MODE,
202  * RADIO_RX_MODE_ADDRESS_FILTER | RADIO_RX_MODE_AUTOACK);
203  */
204 #define RADIO_RX_MODE_ADDRESS_FILTER (1 << 0)
205 #define RADIO_RX_MODE_AUTOACK (1 << 1)
206 #define RADIO_RX_MODE_POLL_MODE (1 << 2)
207 
208 /**
209  * The radio transmission mode controls whether transmissions should
210  * be done using clear channel assessment (if supported by the
211  * radio). If send-on-CCA is enabled, the radio's send function will
212  * wait for a radio-specific time window for the channel to become
213  * clear. If this does not happen, the send function will return
214  * RADIO_TX_COLLISION.
215  */
216 #define RADIO_TX_MODE_SEND_ON_CCA (1 << 0)
217 
218 /* Radio return values when setting or getting radio parameters. */
219 typedef enum {
220  RADIO_RESULT_OK,
221  RADIO_RESULT_NOT_SUPPORTED,
222  RADIO_RESULT_INVALID_VALUE,
223  RADIO_RESULT_ERROR
224 } radio_result_t;
225 
226 /* Radio return values for transmissions. */
227 enum {
228  RADIO_TX_OK,
229  RADIO_TX_ERR,
230  RADIO_TX_COLLISION,
231  RADIO_TX_NOACK,
232 };
233 
234 /**
235  * The structure of a device driver for a radio in Contiki.
236  */
237 struct radio_driver {
238 
239  int (* init)(void);
240 
241  /** Prepare the radio with a packet to be sent. */
242  int (* prepare)(const void *payload, unsigned short payload_len);
243 
244  /** Send the packet that has previously been prepared. */
245  int (* transmit)(unsigned short transmit_len);
246 
247  /** Prepare & transmit a packet. */
248  int (* send)(const void *payload, unsigned short payload_len);
249 
250  /** Read a received packet into a buffer. */
251  int (* read)(void *buf, unsigned short buf_len);
252 
253  /** Perform a Clear-Channel Assessment (CCA) to find out if there is
254  a packet in the air or not. */
255  int (* channel_clear)(void);
256 
257  /** Check if the radio driver is currently receiving a packet */
258  int (* receiving_packet)(void);
259 
260  /** Check if the radio driver has just received a packet */
261  int (* pending_packet)(void);
262 
263  /** Turn the radio on. */
264  int (* on)(void);
265 
266  /** Turn the radio off. */
267  int (* off)(void);
268 
269  /** Get a radio parameter value. */
270  radio_result_t (* get_value)(radio_param_t param, radio_value_t *value);
271 
272  /** Set a radio parameter value. */
273  radio_result_t (* set_value)(radio_param_t param, radio_value_t value);
274 
275  /**
276  * Get a radio parameter object. The argument 'dest' must point to a
277  * memory area of at least 'size' bytes, and this memory area will
278  * contain the parameter object if the function succeeds.
279  */
280  radio_result_t (* get_object)(radio_param_t param, void *dest, size_t size);
281 
282  /**
283  * Set a radio parameter object. The memory area referred to by the
284  * argument 'src' will not be accessed after the function returns.
285  */
286  radio_result_t (* set_object)(radio_param_t param, const void *src,
287  size_t size);
288 
289 };
290 
291 #endif /* RADIO_H_ */
292 
293 /** @} */
294 /** @} */
radio_result_t(* get_object)(radio_param_t param, void *dest, size_t size)
Get a radio parameter object.
Definition: radio.h:280
int(* prepare)(const void *payload, unsigned short payload_len)
Prepare the radio with a packet to be sent.
Definition: radio.h:242
int(* receiving_packet)(void)
Check if the radio driver is currently receiving a packet.
Definition: radio.h:258
radio_result_t(* set_value)(radio_param_t param, radio_value_t value)
Set a radio parameter value.
Definition: radio.h:273
int(* pending_packet)(void)
Check if the radio driver has just received a packet.
Definition: radio.h:261
The structure of a device driver for a radio in Contiki.
Definition: radio.h:237
int(* channel_clear)(void)
Perform a Clear-Channel Assessment (CCA) to find out if there is a packet in the air or not...
Definition: radio.h:255
int radio_value_t
Each radio has a set of parameters that designate the current configuration and state of the radio...
Definition: radio.h:88
int(* send)(const void *payload, unsigned short payload_len)
Prepare & transmit a packet.
Definition: radio.h:248
int(* transmit)(unsigned short transmit_len)
Send the packet that has previously been prepared.
Definition: radio.h:245
int(* off)(void)
Turn the radio off.
Definition: radio.h:267
int(* read)(void *buf, unsigned short buf_len)
Read a received packet into a buffer.
Definition: radio.h:251
radio_result_t(* get_value)(radio_param_t param, radio_value_t *value)
Get a radio parameter value.
Definition: radio.h:270
radio_result_t(* set_object)(radio_param_t param, const void *src, size_t size)
Set a radio parameter object.
Definition: radio.h:286
int(* on)(void)
Turn the radio on.
Definition: radio.h:264