Vergil Cola / Mbed OS MQTTGateway2

Fork of my original MQTTGateway

Dependencies:   mbed-http

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

Committer:
vpcola
Date:
Sat Apr 08 14:43:14 2017 +0000
Revision:
0:a1734fe1ec4b
Initial commit

Who changed what in which revision?

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