Jim Flynn / Mbed OS wifi_Example

wifi test

Dependencies:   X_NUCLEO_IKS01A2 mbed-http

easy-connect/stm-spirit1-rf-driver/source/libs/Contiki_STM32_Library/radio.h@0:24d3eb812fd4, 2018-09-05 (annotated)

Committer:
JMF
Date:
Wed Sep 05 14:28:24 2018 +0000
Revision:
0:24d3eb812fd4
Initial commit

Who changed what in which revision?

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