Enhanced the documentation.
This commit is contained in:
Nicolas Tsiftes
parent
fc6814a104
commit
2284ef5ef2
143
core/dev/radio.h
143
core/dev/radio.h
|
|
@ -49,6 +49,9 @@
|
|||
* Header file for the radio API
|
||||
* \author
|
||||
* Adam Dunkels <adam@sics.se>
|
||||
* Joakim Eriksson <joakime@sics.se>
|
||||
* Niclas Finne <nfi@sics.se>
|
||||
* Nicolas Tsiftes <nvt@sics.se>
|
||||
*/
|
||||
|
||||
#ifndef RADIO_H_
|
||||
|
|
@ -56,28 +59,106 @@
|
|||
|
||||
#include <stddef.h>
|
||||
|
||||
/**
|
||||
* Each radio has a set of parameters that designate the current
|
||||
* configuration and state of the radio. Parameters can either have
|
||||
* values of type radio_value_t, or, when this type is insufficient, a
|
||||
* generic object that is specified by a memory pointer and the size
|
||||
* of the object.
|
||||
*
|
||||
* The radio_value_t type is set to an integer type that can hold most
|
||||
* values used to configure the radio, and is therefore the most
|
||||
* common type used for a parameter. Certain parameters require
|
||||
* objects of a considerably larger size than radio_value_t, however,
|
||||
* and in these cases the documentation below for the parameter will
|
||||
* indicate this.
|
||||
*
|
||||
* All radio parameters that can vary during runtime are prefixed by
|
||||
* "RADIO_PARAM", whereas those "parameters" that are guaranteed to
|
||||
* remain immutable are prefixed by "RADIO_CONST". Each mutable
|
||||
* parameter has a set of valid parameter values. When attempting to
|
||||
* set a parameter to an invalid value, the radio will return
|
||||
* RADIO_RESULT_INVALID_VALUE.
|
||||
*
|
||||
* Some radios support only a subset of the defined radio parameters.
|
||||
* When trying to set or get such an unsupported parameter, the radio
|
||||
* will return RADIO_RESULT_NOT_SUPPORTED.
|
||||
*/
|
||||
|
||||
typedef int radio_value_t;
|
||||
typedef unsigned radio_param_t;
|
||||
|
||||
enum {
|
||||
|
||||
/* Radio power mode determines if the radio is on
|
||||
(RADIO_POWER_MODE_ON) or off (RADIO_POWER_MODE_OFF). */
|
||||
RADIO_PARAM_POWER_MODE,
|
||||
|
||||
/*
|
||||
* Channel used for radio communication. The channel depends on the
|
||||
* communication standard used by the radio. The values can range
|
||||
* from RADIO_CONST_CHANNEL_MIN to RADIO_CONST_CHANNEL_MAX.
|
||||
*/
|
||||
RADIO_PARAM_CHANNEL,
|
||||
|
||||
/* Personal area network identifier, which is used by the address filter. */
|
||||
RADIO_PARAM_PAN_ID,
|
||||
|
||||
/* Short address (16 bits) for the radio, which is used by the address
|
||||
filter. */
|
||||
RADIO_PARAM_16BIT_ADDR,
|
||||
/** Address handler take care of address filtering and sending autoack */
|
||||
|
||||
/* Address handler take care of address filtering and sending auto-ACK.
|
||||
(See below for more information.) */
|
||||
RADIO_PARAM_ADDRESS_HANDLER,
|
||||
/** Transmission power in dBm */
|
||||
|
||||
/*
|
||||
* Transmission power in dBm. The values can range from
|
||||
* RADIO_CONST_TXPOWER_MIN to RADIO_CONST_TXPOWER_MAX.
|
||||
*
|
||||
* Some radios restrict the available values to a subset of this
|
||||
* range. If an unavailable TXPOWER value is requested to be set,
|
||||
* the radio may select another TXPOWER close to the requested
|
||||
* one. When getting the value of this parameter, the actual value
|
||||
* used by the radio will be returned.
|
||||
*/
|
||||
RADIO_PARAM_TXPOWER,
|
||||
/** Received signal strength in dBm */
|
||||
|
||||
/*
|
||||
* Clear channel assessment threshold in dBm. This threshold
|
||||
* determines the minimum RSSI level at which the radio will assume
|
||||
* that there is a packet in the air.
|
||||
*
|
||||
* The CCA threshold must be set to a level above the noise floor of
|
||||
* the deployment. Otherwise mechanisms such as send-on-CCA and
|
||||
* low-power-listening duty cycling protocols may not work
|
||||
* correctly. Hence, the default value of the system may not be
|
||||
* optimal for any given deployment.
|
||||
*/
|
||||
RADIO_PARAM_CCA_THRESHOLD,
|
||||
|
||||
/* Received signal strength indicator in dBm. */
|
||||
RADIO_PARAM_RSSI,
|
||||
|
||||
/** 64 bit addresses need to be used with radio.get_object()/set_object() */
|
||||
/*
|
||||
* Long (64 bits) address for the radio, which is used by the address filter.
|
||||
* The address is specified in network byte order.
|
||||
*
|
||||
* Because this parameter value is larger than what fits in radio_value_t,
|
||||
* it needs to be used with radio.get_object()/set_object().
|
||||
*/
|
||||
RADIO_PARAM_64BIT_ADDR,
|
||||
|
||||
/** Constants (read only) */
|
||||
/* Constants (read only) */
|
||||
|
||||
/* The lowest radio channel. */
|
||||
RADIO_CONST_CHANNEL_MIN,
|
||||
/* The highest radio channel. */
|
||||
RADIO_CONST_CHANNEL_MAX,
|
||||
|
||||
/* The minimum transmission power in dBm. */
|
||||
RADIO_CONST_TXPOWER_MIN,
|
||||
/* The maximum transmission power in dBm. */
|
||||
RADIO_CONST_TXPOWER_MAX
|
||||
};
|
||||
|
||||
|
|
@ -87,9 +168,22 @@ enum {
|
|||
RADIO_POWER_MODE_ON
|
||||
};
|
||||
|
||||
/* Bit flags for the address handler */
|
||||
#define RADIO_ADDRESS_HANDLER_FILTER 1
|
||||
#define RADIO_ADDRESS_HANDLER_AUTOACK 2
|
||||
/**
|
||||
* The address handler is an abstraction responsible for address
|
||||
* filtering and automatic transmission of acknowledgements in the
|
||||
* radio (if such operations are supported by the radio).
|
||||
*
|
||||
* There are different options that can be used like address filter
|
||||
* on/off, autoack on/off. A single parameter is used to set them
|
||||
* simultaneous as an atomic operation.
|
||||
*
|
||||
* To enable both address filter and transmissions of autoack:
|
||||
*
|
||||
* NETSTACK_RADIO.set_value(RADIO_PARAM_ADDRESS_HANDLER,
|
||||
* RADIO_ADDRESS_HANDLER_FILTER | RADIO_ADDRESS_HANDLER_AUTOACK);
|
||||
*/
|
||||
#define RADIO_ADDRESS_HANDLER_FILTER (1 << 0)
|
||||
#define RADIO_ADDRESS_HANDLER_AUTOACK (1 << 1)
|
||||
|
||||
/* Radio return values when setting or getting radio parameters. */
|
||||
typedef enum {
|
||||
|
|
@ -99,6 +193,14 @@ typedef enum {
|
|||
RADIO_RESULT_ERROR
|
||||
} radio_result_t;
|
||||
|
||||
/* Radio return values for transmissions. */
|
||||
enum {
|
||||
RADIO_TX_OK,
|
||||
RADIO_TX_ERR,
|
||||
RADIO_TX_COLLISION,
|
||||
RADIO_TX_NOACK,
|
||||
};
|
||||
|
||||
/**
|
||||
* The structure of a device driver for a radio in Contiki.
|
||||
*/
|
||||
|
|
@ -134,31 +236,28 @@ struct radio_driver {
|
|||
/** Turn the radio off. */
|
||||
int (* off)(void);
|
||||
|
||||
/** Get a radio parameter */
|
||||
/** Get a radio parameter value. */
|
||||
radio_result_t (* get_value)(radio_param_t param, radio_value_t *value);
|
||||
|
||||
/** Set a radio parameter */
|
||||
/** Set a radio parameter value. */
|
||||
radio_result_t (* set_value)(radio_param_t param, radio_value_t value);
|
||||
|
||||
/** Get a radio object (for example a 64 bit address) */
|
||||
/**
|
||||
* Get a radio parameter object. The argument 'dest' must point to a
|
||||
* memory area of at least 'size' bytes, and this memory area will
|
||||
* contain the parameter object if the function succeeds.
|
||||
*/
|
||||
radio_result_t (* get_object)(radio_param_t param, void *dest, size_t size);
|
||||
|
||||
/** Set a radio object (for example a 64 bit address). The data
|
||||
is copied and the object memory will not be accessed after the call.
|
||||
*/
|
||||
/**
|
||||
* Set a radio parameter object. The memory area referred to by the
|
||||
* argument 'src' will not be accessed after the function returns.
|
||||
*/
|
||||
radio_result_t (* set_object)(radio_param_t param, const void *src,
|
||||
size_t size);
|
||||
|
||||
};
|
||||
|
||||
/* Generic radio return values. */
|
||||
enum {
|
||||
RADIO_TX_OK,
|
||||
RADIO_TX_ERR,
|
||||
RADIO_TX_COLLISION,
|
||||
RADIO_TX_NOACK,
|
||||
};
|
||||
|
||||
#endif /* RADIO_H_ */
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue