Toyomasa Watarai / easy-connect-type-yd

Easily add all supported connectivity methods to your mbed OS project

Dependencies:   type-yd-driver

stm-spirit1-rf-driver/source/libs/Contiki_STM32_Library/radio.h@0:615f90842ce8, 2017-07-12 (annotated)

Committer:
MACRUM
Date:
Wed Jul 12 10:52:58 2017 +0000
Revision:
0:615f90842ce8
Initial commit

Who changed what in which revision?

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