From 2284ef5ef2168181044c90bac452bd4f4f094dc1 Mon Sep 17 00:00:00 2001 From: Nicolas Tsiftes Date: Mon, 7 Apr 2014 15:31:50 +0200 Subject: [PATCH] Enhanced the documentation. --- core/dev/radio.h | 143 +++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 121 insertions(+), 22 deletions(-) diff --git a/core/dev/radio.h b/core/dev/radio.h index eed4f0929..05b87f225 100644 --- a/core/dev/radio.h +++ b/core/dev/radio.h @@ -49,6 +49,9 @@ * Header file for the radio API * \author * Adam Dunkels + * Joakim Eriksson + * Niclas Finne + * Nicolas Tsiftes */ #ifndef RADIO_H_ @@ -56,28 +59,106 @@ #include +/** + * 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_ */