RIOT/drivers/include/cc2420.h

/*
 * Copyright (C) 2015-2016 Freie Universität Berlin
 *
 * This file is subject to the terms and conditions of the GNU Lesser
 * General Public License v2.1. See the file LICENSE in the top level
 * directory for more details.
 */

/**
 * @defgroup    drivers_cc2420 CC2420 driver
 * @ingroup     drivers
 * @brief       Implementation of the CC2420 radio driver
 * @{
 *
 * @file
 * @brief       Interface definition for the CC2420 driver
 *
 * @author      Thomas Eichinger <thomas.eichinger@fu-berlin.de>
 * @author      Hauke Petersen <hauke.petersen@fu-berlin.de>
 */

#ifndef CC2420_H
#define CC2420_H

#include <stdint.h>

#include "periph/spi.h"
#include "periph/gpio.h"

#include "net/netdev2.h"
#include "net/netdev2/ieee802154.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief   Maximum possible packet size in byte
 */
#define CC2420_PKT_MAXLEN       (127U)

/**
 * @brief   Default addresses used if the CPUID module is not present
 *
 * In case this address is used, that short address will be created by using the
 * last two bytes of the long address.
 * @{
 */
#define CC2420_ADDR_FALLBACK    {0x12, 0x22, 0x33, 0x44, 0x55, 0x66, 0x08, 0x15}
/** @} */

/**
 * @brief   PAN ID configuration
 */
#define CC2420_PANID_DEFAULT    (0x0023)

/**
  * @brief   Channel configuration
  * @{
  */
#define CC2420_CHAN_MIN         (11U)
#define CC2420_CHAN_MAX         (26U)
#define CC2420_CHAN_DEFAULT     (26U)
/** @} */

/**
 * @brief   Default TX power configuration [in dBm]
 * @{
 */
#define CC2420_TXPOWER_MIN      (-25)
#define CC2420_TXPOWER_MAX      (0)
#define CC2420_TXPOWER_DEFAULT  (0)
/** @} */

/**
 * @brief   A couple of return values used in this driver
 */
enum {
    CC2420_RET_CHAN_OK      = 2,
};

/**
 * @brief   Struct holding all parameters needed for device initialization
 */
typedef struct cc2420_params {
    spi_t spi;              /**< SPI bus the device is connected to */
    spi_speed_t spi_clk;    /**< SPI speed to use */
    gpio_t pin_cs;          /**< pin connected to chip select */
    gpio_t pin_fifo;        /**< pin connected to the FIFO interrupt pin */
    gpio_t pin_fifop;       /**< pin connected to the FIFOP interrupt pin */
    gpio_t pin_cca;         /**< pin connected to CCA */
    gpio_t pin_sfd;         /**< pin connected to 'start of frame delimiter' */
    gpio_t pin_vrefen;      /**< pin connected to the Vref enable pin */
    gpio_t pin_reset;       /**< pin connected to the reset pin */
} cc2420_params_t;

/**
 * @brief   Device descriptor for CC2420 radio devices
 */
typedef struct {
    /* netdev fields */
    netdev2_ieee802154_t netdev;
    /* device specific fields */
    cc2420_params_t params;     /**< hardware interface configuration */
    /* device state fields */
    uint8_t state;              /**< current state of the radio */
    uint16_t options;           /**< state of used options */
} cc2420_t;

/**
 * @brief   Setup the device descriptor for the given device
 *
 * @param[out] dev          device descriptor
 * @param[in]  params       device parameters
 *
 * @return                  0 on success
 * @return                  -1 on error
 */
void cc2420_setup(cc2420_t *dev, const cc2420_params_t *params);

/**
 * @brief   Initialize a given CC2420 device
 *
 * @param[out] dev          device descriptor
 *
 * @return                  0 on success
 * @return                  <0 on error
 */
int cc2420_init(cc2420_t *dev);

/**
 * @brief   Trigger a hardware reset and configure radio with default values
 *
 * @param[in] dev           device to reset
 *
 * @return  TODO
 */
int cc2420_reset(cc2420_t *dev);

/**
 * @brief   Trigger a clear channel assessment
 *
 * @param[in] dev           device to use
 *
 * @return                  true if channel is clear
 * @return                  false if channel is busy
 */
bool cc2420_cca(cc2420_t *dev);

/**
 * @brief   Get the short address of the given device
 *
 * @param[in]  dev          device to read from
 * @param[out] addr         memory to write the 2 byte address into
 */
void cc2420_get_addr_short(cc2420_t *dev, uint8_t *addr);

/**
 * @brief   Set the short address of the given device
 *
 * @param[in] dev           device to write to
 * @param[in] addr          (2-byte) short address to set
 */
void cc2420_set_addr_short(cc2420_t *dev, uint8_t *addr);

/**
 * @brief   Get the configured long address of the given device
 *
 * @param[in] dev           device to read from
 *
 * @return                  the currently set (8-byte) long address
 */
void cc2420_get_addr_long(cc2420_t *dev, uint8_t *addr_long);

/**
 * @brief   Set the long address of the given device
 *
 * @param[in] dev           device to write to
 * @param[in] addr          (8-byte) long address to set
 */
void cc2420_set_addr_long(cc2420_t *dev, uint8_t *addr_long);

/**
 * @brief   Get the configured PAN ID of the given device
 *
 * @param[in] dev           device to read from
 *
 * @return                  the currently set PAN ID
 */
uint16_t cc2420_get_pan(cc2420_t *dev);

/**
 * @brief   Set the PAN ID of the given device
 *
 * @param[in] dev           device to write to
 * @param[in] pan           PAN ID to set
 */
void cc2420_set_pan(cc2420_t *dev, uint16_t pan);

/**
 * @brief   Get the configured channel of the given device
 *
 * @param[in] dev           device to read from
 *
 * @return                  the currently set channel
 */
uint16_t cc2420_get_chan(cc2420_t *dev);

/**
 * @brief   Set the channel of the given device
 *
 * @param[in] dev           device to write to
 * @param[in] chan          channel to set
 */
int cc2420_set_chan(cc2420_t *dev, uint16_t chan);

/**
 * @brief   Get the configured transmission power of the given device [in dBm]
 *
 * @param[in] dev           device to read from
 *
 * @return                  configured transmission power in dBm
 */
int16_t cc2420_get_txpower(cc2420_t *dev);

/**
 * @brief   Set the transmission power of the given device [in dBm]
 *
 * If the device does not support the exact dBm value given, it will set a value
 * as close as possible to the given value. If the given value is larger or
 * lower then the maximal or minimal possible value, the min or max value is
 * set, respectively.
 *
 * @param[in] dev           device to write to
 * @param[in] txpower       transmission power in dBm
 */
void cc2420_set_txpower(cc2420_t *dev, int16_t txpower);

/**
 * @brief   Enable or disable driver specific options
 *
 * @param[in] dev           device to set/clear option flag for
 * @param[in] option        option to enable/disable
 * @param[in] state         true for enable, false for disable
 */
int cc2420_set_option(cc2420_t *dev, uint16_t option, bool state);

/**
 * @brief   Set the state of the given device (trigger a state change)
 *
 * @param[in] dev           device to change state of
 * @param[in] state         the targeted new state
 */
int cc2420_set_state(cc2420_t *dev, netopt_state_t state);

/**
 * @brief   Get the state of the given device
 *
 * @param[in] dev           device to change state of
 *
 * @return                  the device's current state
 */
netopt_state_t cc2420_get_state(cc2420_t *dev);

/**
 * @brief   Convenience function for simply sending data
 *
 * @note This function ignores the PRELOADING option
 *
 * @param[in] dev           device to use for sending
 * @param[in] data          data to send (must include IEEE802.15.4 header)
 * @param[in] len           length of @p data
 *
 * @return                  number of bytes that were actually send
 * @return                  0 on error
 */
size_t cc2420_send(cc2420_t *dev, const struct iovec *data, int count);

/**
 * @brief   Prepare for sending of data
 *
 * This function puts the given device into the TX state, so no receiving of
 * data is possible after it was called.
 *
 * @param[in] dev            device to prepare for sending
 */
size_t cc2420_tx_prepare(cc2420_t *dev, const struct iovec *data, int count);

/**
 * @brief   Trigger sending of data previously loaded into transmit buffer
 *
 * @param[in] dev           device to trigger
 */
void cc2420_tx_exec(cc2420_t *dev);

/**
 * @brief   Read a chunk of data from the receive buffer of the given device
 *
 * @param[in]  dev          device to read from
 * @param[out] data         buffer to write data to
 * @param[in]  len          number of bytes to read from device
 * @param[in]  offset       offset in the receive buffer
 */
int cc2420_rx(cc2420_t *dev, uint8_t *buf, size_t max_len, void *info);

#ifdef __cplusplus
}
#endif

#endif /* CC2420_H */
/** @} */