Vergil Cola / Mbed OS MQTTGatewayK64

Fork of my MQTTGateway

Dependencies:   mbed-http

easy-connect/stm-spirit1-rf-driver/source/libs/Contiki_STM32_Library/radio.h@0:f1d3878b8dd9, 2017-04-08 (annotated)

Committer:
vpcola
Date:
Sat Apr 08 14:45:51 2017 +0000
Revision:
0:f1d3878b8dd9
Initial commit

Who changed what in which revision?

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