mirror of
https://github.com/oliverschmidt/contiki.git
synced 2024-08-26 10:28:58 +00:00
Enhanced the documentation.
This commit is contained in:
parent
fc6814a104
commit
2284ef5ef2
143
core/dev/radio.h
143
core/dev/radio.h
@ -49,6 +49,9 @@
|
|||||||
* Header file for the radio API
|
* Header file for the radio API
|
||||||
* \author
|
* \author
|
||||||
* Adam Dunkels <adam@sics.se>
|
* Adam Dunkels <adam@sics.se>
|
||||||
|
* Joakim Eriksson <joakime@sics.se>
|
||||||
|
* Niclas Finne <nfi@sics.se>
|
||||||
|
* Nicolas Tsiftes <nvt@sics.se>
|
||||||
*/
|
*/
|
||||||
|
|
||||||
#ifndef RADIO_H_
|
#ifndef RADIO_H_
|
||||||
@ -56,28 +59,106 @@
|
|||||||
|
|
||||||
#include <stddef.h>
|
#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 int radio_value_t;
|
||||||
typedef unsigned radio_param_t;
|
typedef unsigned radio_param_t;
|
||||||
|
|
||||||
enum {
|
enum {
|
||||||
|
|
||||||
|
/* Radio power mode determines if the radio is on
|
||||||
|
(RADIO_POWER_MODE_ON) or off (RADIO_POWER_MODE_OFF). */
|
||||||
RADIO_PARAM_POWER_MODE,
|
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,
|
RADIO_PARAM_CHANNEL,
|
||||||
|
|
||||||
|
/* Personal area network identifier, which is used by the address filter. */
|
||||||
RADIO_PARAM_PAN_ID,
|
RADIO_PARAM_PAN_ID,
|
||||||
|
|
||||||
|
/* Short address (16 bits) for the radio, which is used by the address
|
||||||
|
filter. */
|
||||||
RADIO_PARAM_16BIT_ADDR,
|
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,
|
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,
|
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,
|
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,
|
RADIO_PARAM_64BIT_ADDR,
|
||||||
|
|
||||||
/** Constants (read only) */
|
/* Constants (read only) */
|
||||||
|
|
||||||
|
/* The lowest radio channel. */
|
||||||
RADIO_CONST_CHANNEL_MIN,
|
RADIO_CONST_CHANNEL_MIN,
|
||||||
|
/* The highest radio channel. */
|
||||||
RADIO_CONST_CHANNEL_MAX,
|
RADIO_CONST_CHANNEL_MAX,
|
||||||
|
|
||||||
|
/* The minimum transmission power in dBm. */
|
||||||
RADIO_CONST_TXPOWER_MIN,
|
RADIO_CONST_TXPOWER_MIN,
|
||||||
|
/* The maximum transmission power in dBm. */
|
||||||
RADIO_CONST_TXPOWER_MAX
|
RADIO_CONST_TXPOWER_MAX
|
||||||
};
|
};
|
||||||
|
|
||||||
@ -87,9 +168,22 @@ enum {
|
|||||||
RADIO_POWER_MODE_ON
|
RADIO_POWER_MODE_ON
|
||||||
};
|
};
|
||||||
|
|
||||||
/* Bit flags for the address handler */
|
/**
|
||||||
#define RADIO_ADDRESS_HANDLER_FILTER 1
|
* The address handler is an abstraction responsible for address
|
||||||
#define RADIO_ADDRESS_HANDLER_AUTOACK 2
|
* 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. */
|
/* Radio return values when setting or getting radio parameters. */
|
||||||
typedef enum {
|
typedef enum {
|
||||||
@ -99,6 +193,14 @@ typedef enum {
|
|||||||
RADIO_RESULT_ERROR
|
RADIO_RESULT_ERROR
|
||||||
} radio_result_t;
|
} 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.
|
* The structure of a device driver for a radio in Contiki.
|
||||||
*/
|
*/
|
||||||
@ -134,31 +236,28 @@ struct radio_driver {
|
|||||||
/** Turn the radio off. */
|
/** Turn the radio off. */
|
||||||
int (* off)(void);
|
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);
|
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);
|
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);
|
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,
|
radio_result_t (* set_object)(radio_param_t param, const void *src,
|
||||||
size_t size);
|
size_t size);
|
||||||
|
|
||||||
};
|
};
|
||||||
|
|
||||||
/* Generic radio return values. */
|
|
||||||
enum {
|
|
||||||
RADIO_TX_OK,
|
|
||||||
RADIO_TX_ERR,
|
|
||||||
RADIO_TX_COLLISION,
|
|
||||||
RADIO_TX_NOACK,
|
|
||||||
};
|
|
||||||
|
|
||||||
#endif /* RADIO_H_ */
|
#endif /* RADIO_H_ */
|
||||||
|
|
||||||
|
|
||||||
|
Loading…
Reference in New Issue
Block a user