iqrf.h

Go to the documentation of this file.

#ifndef IQRF_H_INCLUDED
#define IQRF_H_INCLUDED
/**********************************************************************/
/*
 * Copyright (c) 2016, Jetro AS
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright notice,
 *    this list of conditions and the following disclaimer in the documentation
 *    and/or other materials provided with the distribution.
 * 3. The name of the author may not be used to endorse or promote products
 *    derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONRIBUTORS ``AS IS'' AND ANY EXPRESS
 * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
 * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
 * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
 * OF SUCH DAMAGE.
 *
 * This file is part of the EVE platform.
 */

/**
 * \file
 * @brief Driver for IQRF radio modules
 *
 * @author DT, Jetro AS
 */ /******************************************************************/

#include <core/mwork.h>
#include <core/uwork.h>
#include <dev/spi.h>

/**
 * \defgroup iqrf IQRF module driver
 * \ingroup extdrv
 * \{
 *
 */

/**
 * @brief Custom periferal number for Bridge
 */
#define IQRF_PNUM_BRIDGE        (0x30)

/**
 * @brief SPI buffer length (max IQRF packet size + 4)
 */
#define IQRF_SPI_BUFFER_LENGTH  (68)

/**
 * @brief Worst estimate for response timeslot length in 10 ms. intervals.
 */
#define IQRF_RESPONSE_TIMESLOT_LENGTH_WORST_ESTIMATE  (5)

/**
 * @brief Value used as an invalid timestamp value
 */
#define IQRF_INVALID_TIMESTAMP  (0xFFFFFFFF)

/* forward */ struct iqrf_t;

/**
 * Possible response types
 */
enum iqrf_response_type_t
{
  IQRF_TYPE_CONFIRMATION,                 //!< DPA Confirmation
  IQRF_TYPE_RESPONSE,                     //!< DPA Response
  IQRF_TYPE_ERROR,                        //!< DPA error
  IQRF_TYPE_TIMEOUT,                      //!< Timeout
};

/**
 * DPA protocol header
 */
struct iqrf_dpa_header_t
{
  uint16_t NADR;                          //!< Node address
  uint8_t PNUM;                           //!< Periphery number (address)
  uint8_t PCMD;                           //!< Periphery command
  uint16_t HWPID;                         //!< Hardware profile ID
};

/**
 * DPA request
 */
struct iqrf_dpa_request_t
{
  struct iqrf_dpa_header_t Hdr;           //!< DPA header
  uint8_t Data[0];                        //!< Data, associated with the request
};

/**
 * DPA confirmation message
 */
struct iqrf_dpa_confirmation_t
{
  struct iqrf_dpa_header_t Hdr;           //!< DPA header
  uint8_t ErrN;                           //!< Error number (= 0xFF for confirmation messages)
  uint8_t DpaValue;                       //!< DPA value
  uint8_t HopsRequest;                    //!< Number of hops in the forward (request) distribution path
  uint8_t TimeslotRequest;                //!< Timeslot length for the request in 10 ms intervals
  uint8_t HopsResponse;                   //!< Number of hops in the backward (response) distribution path
};

/**
 * DPA response message
 */
struct iqrf_dpa_response_t
{
  struct iqrf_dpa_header_t Hdr;           //!< DPA header
  uint8_t ErrN;                           //! Error number (= 0x00 for response messages)
  uint8_t DpaValue;                       //!< DPA value
  uint8_t Data[0];                        //!< Data, associated with the response
};

/**
 * DPA broadcast message
 */
struct iqrf_dpa_broadcast_t
{
  struct iqrf_dpa_header_t Hdr;           //!< DPA header
  uint8_t Data[0];                        //!< Data, associated with the response
};

/**
 * Per-instance IQRF global handlers (callbacks) table
 */
struct iqrf_global_handlers_t
{
  /** Called when an IQRF device goes offline */
  void (*OnOffline)(const struct iqrf_t *Iqrf);

  /** Called when an IQRF device goes online */
  void (*OnOnline)(const struct iqrf_t *Iqrf);

  /** Called when an IQRF device receives a DPA request */
  void (*OnDpaRequest)(const struct iqrf_t *Iqrf, uint8_t Cmd, const uint8_t *Data, uint8_t Length);

  /** Called when an IQRF device receives a broadcast DPA request */
  void (*OnBroadcastRequest)(const struct iqrf_t *Iqrf, const struct iqrf_dpa_broadcast_t *Dpa, uint8_t Length);

  /** Called when an IQRF device receives an FRC request */
  void (*OnFrcRequest)(const struct iqrf_t *Iqrf, uint8_t Cmd, const uint8_t *Data, uint8_t Length);
};

/**
 * Per-request handler (callback), which receives notification about the request lifecycle
 *
 * @param Iqrf        IQRF instance
 * @param Type        Type of notification
 * @param Dpa         Pointer to the DPA response structure. It can contain iqrf_dpa_confirmation_t as well.
 * @param Length      Length of the data in the DPA response.
 */
typedef void (*iqrf_response_handler_t)(const struct iqrf_t *Iqrf,
    enum iqrf_response_type_t Type,
    const struct iqrf_dpa_response_t *Dpa,
    uint8_t Length);

/**
 * IQRF module state structure
 */
struct iqrf_state_t
{
  const struct iqrf_t *Iqrf;              //!< Module instance
  uint8_t Nadr;                           //!< Node's NADR
  uint8_t RxLen;                          //!< Length of data in Rx buffer
  uint8_t TxLen[2];                       //!< Length of data in Tx buffers
  uint8_t TxIdx;                          //!< Index of currently used TX buffer
  uint8_t Pos;                            //!< Position of the currently transferred byte in a buffer
  uint8_t /*enum iqrf_xfer_phase_t*/ Phase; //!< Thansfer phase
  bool XferStatus;                        //!< True if last transfer has finished successfully.
  uint8_t Channel;                        //!< Radio channel
  uint8_t /*enum iqrfapp_state_t*/ State; //!< State
  uint16_t Hwpid;                         //!< HWPID
  struct work_t Work;                     //!< IQRF work
  struct uwork_t UWork;                   //!< IQRF microsecond scheduler
  struct mwork_t RoutingTimer;            //!< IQRF millisecond scheduler

  uint8_t HopsRequest;                    //!< Copy of HopsRequest from the last confirmation message
  uint8_t TimeslotRequest;                //!< Copy of TimeslotRequest from the last confirmation message
  uint8_t HopsResponse;                   //!< Copy of HopsResponse from the last confirmation message
  uint8_t TimeslotResponse;               /*!< Calculated or predicted timeslot length for 
                                               the backward (response) distribution path */
  uint32_t ConfirmationTimestamp;         //!< Timestamp for the last confirmation message
  iqrf_response_handler_t ResponseHandler; //!< Per-request response handler (callback)

  uint8_t Rx[IQRF_SPI_BUFFER_LENGTH];     //!< SPI receive buffer (max IQRF packet size + 4)
  uint8_t Tx[2][IQRF_SPI_BUFFER_LENGTH];  //!< SPI transmit buffers (max IQRF packet size + 4)
};

/**
 * @brief IQRF instance structure
 */
struct iqrf_t
{
  struct iqrf_state_t *State;             //!< IRRF state
  const struct spi_t* Spi;                //!< Spi instance
  struct spi_cs_t SpiCs;                  //!< Spi CS flags
  uint32_t SpiBaudrate;                   //!< Spi speed (should be 250000 for IQRF)
  const struct iqrf_global_handlers_t *Handlers; //!< pointer to the IQRF global handlers table
  uint8_t IrqPin;                         //!< IRQ pin
  bool IsCoordinator;                     //!< True if the interface represents an IQRF coordinator
};

/**
 * IQRF interrupt handler
 *
 * @param Iqrf        IQRF instance
 */
void IqrfInterruptCb(const struct iqrf_t *Iqrf);

/**
 * Init an IQRF driver instance
 *
 * @param Iqrf        IQRF instance
 */
void IqrfInit(const struct iqrf_t *Iqrf);

/**
 * Checks if an IQRF driver is busy
 *
 * @param Iqrf        IQRF instance
 * @return            true if the instance is busy, false if IqrfSendDpaRequest can be called.
 */
bool IqrfIsBusy(const struct iqrf_t* Iqrf);

/**
 * Send a DPA request to the IQRF module
 *
 * @param Iqrf        IQRF instance
 * @param ResponseHandler A handler (callback), which receives notification about the request lifecycle
 * @param Request     DPA request
 * @param DataLen     Length of data field in the DPA request
 * @return            true if the request was sent to the IQRF, false in case of any error
 */
bool IqrfSendDpaRequest(const struct iqrf_t *Iqrf,
    iqrf_response_handler_t ResponseHandler,
    const struct iqrf_dpa_request_t *Request,
    uint8_t DataLen);

/**
 * Send a response to a DPA request
 *
 * @param Iqrf        IQRF instance
 * @param Data        DPA response data
 * @param DataLen     Length of the DPA response data
 * @return            true if the response was sent to the IQRF, false in case of any error
 */
bool IqrfSendDpaResponse(const struct iqrf_t *Iqrf, const uint8_t *Data, uint8_t DataLen);

/**
 * Send a response with error code
 *
 * @param Iqrf        IQRF instance
 * @param ErrorCode   Error code
 * @return            true if the response was sent to the IQRF, false in case of any error
 */
bool IqrfSendDpaError(const struct iqrf_t* Iqrf, uint8_t ErrorCode);

/**
 * Send a response to a FRC request
 *
 * @param Iqrf        IQRF instance
 * @param Status      FRC status
 * @return            true if the response was sent to the IQRF, false in case of any error
 */
bool IqrfSendFrcResponse(const struct iqrf_t* Iqrf, uint16_t Status);

/**
 * Get time in system ticks required to complete
 * a routing with the given parameters
 *
 * @param HopsRequest HopsRequest field of the confirmation message
 * @param TimeslotRequest TimeslotRequest field of the confirmation message
 * @param HopsResponse HopsResponse field of the confirmation message
 * @param TimeslotResponse Expected duration of the response message, number of timeslots
 *
 * @return            Expected routing time in system tick intervals
 */
uint32_t IqrfGetExpectedRoutingTime(
    uint8_t HopsRequest,
    uint8_t TimeslotRequest,
    uint8_t HopsResponse,
    uint8_t TimeslotResponse);

/**
 * Get point in time when routing is going to be completed.
 *
 * @param Iqrf        IQRF instance
 *
 * @return            System time when routing is expected to be completed.
 *                    IQRF_INVALID_TIMESTAMP if no routing is in progress.
 */
uint32_t IqrfGetExpectedRoutingCompleteTimestamp(const struct iqrf_t* Iqrf);

/** @} */

#endif /* IQRF_H_INCLUDED */