nrf24l01p.h

Go to the documentation of this file.

// Important copyright notice:
// Large parts of this file were copied from Mikael Patel's Cosa library, which copyright appears below
// Content has been adapted to use FastArduino original parts, under Copyright (c) 2016, Jean-Francois Poilpret
 
/*
 * Copyright (C) 2013-2015, Mikael Patel
 * Copyright (C) 2016-2022, Jean-Francois Poilpret
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * This file was originally part of the Arduino Che Cosa project,
 * it has been adapted and refactored to FastArduino library.
 */
 
 
#ifndef NRF24L01_HH
#define NRF24L01_HH
 
#include <stddef.h>
#include "../utilities.h"
#include "../errors.h"
#include "../time.h"
#include "../spi.h"
#include "../int.h"
#include "nrf24l01p_internals.h"
 
namespace devices
{
    namespace rf
    {
    }
}
 
namespace devices::rf
{
    template<board::DigitalPin CSN, board::DigitalPin CE> class NRF24L01 : public spi::SPIDevice<CSN>
    {
    public:
        static const uint8_t BROADCAST = 0x00;
 
        static const size_t DEVICE_PAYLOAD_MAX = 32;
 
        static const size_t PAYLOAD_MAX = DEVICE_PAYLOAD_MAX - 2;
 
        NRF24L01(uint16_t net, uint8_t dev);
 
        uint8_t get_channel() const
        {
            return channel_;
        }
 
        uint16_t get_network_address() const
        {
            return addr_.network;
        }
 
        uint8_t get_device_address() const
        {
            return addr_.device;
        }
 
        void set_address(int16_t net, uint8_t dev)
        {
            addr_.network = net;
            addr_.device = dev;
        }
 
        void set_channel(uint8_t channel)
        {
            channel_ = channel;
        }
 
        void begin();
 
        void end()
        {
            powerdown();
        }
 
        void powerup();
 
        void standby();
 
        void powerdown();
 
        template<typename T, typename TREF = const T&>
        int send(uint8_t dest, uint8_t port, TREF buf)
        {
            return send_(dest, port, (const uint8_t*) &buf, sizeof(T));
        }
 
        int send(uint8_t dest, uint8_t port)
        {
            return send_(dest, port, nullptr, 0);
        }
 
        template<typename T, typename TREF = T&>
        int recv(uint8_t& src, uint8_t& port, TREF buf, uint32_t ms = 0L)
        {
            return recv_(src, port, (uint8_t*) &buf, sizeof(T), ms);
        }
 
        int recv(uint8_t& src, uint8_t& port, uint32_t ms = 0L)
        {
            return recv_(src, port, nullptr, 0, ms);
        }
 
        void set_output_power_level(int8_t dBm);
 
        uint16_t get_trans() const
        {
            return trans_;
        }
 
        uint16_t get_retrans() const
        {
            return retrans_;
        }
 
        uint16_t get_drops() const
        {
            return drops_;
        }
 
        template<typename T, typename TREF = const T&>
        int broadcast(uint8_t port, TREF buf)
        {
            return send(BROADCAST, port, buf);
        }
 
        bool is_broadcast() const
        {
            return (dest_ == BROADCAST);
        }
 
    protected:
        int send_(uint8_t dest, uint8_t port, const uint8_t* buf, size_t len);
        int recv_(uint8_t& src, uint8_t& port, uint8_t* buf, size_t size, uint32_t ms);
 
        enum class Command : uint8_t
        {
            R_REGISTER = 0x00, 
            W_REGISTER = 0x20, 
            REG_MASK = 0x1f,   
 
            R_RX_PAYLOAD = 0x61, 
            W_TX_PAYLOAD = 0xa0, 
 
            FLUSH_TX = 0xe1, 
            FLUSH_RX = 0xe2, 
 
            REUSE_TX_PL = 0xe3, 
 
            R_RX_PL_WID = 0x60, 
 
            W_ACK_PAYLOAD = 0xa8, 
            PIPE_MASK = 0x07,    
 
            W_TX_PAYLOAD_NO_ACK = 0xb0, 
            NOP = 0xff                  
        };
 
        enum class Register : uint8_t
        {
            CONFIG = 0x00,      
            EN_AA = 0x01,       
            EN_RXADDR = 0x02,   
            SETUP_AW = 0x03,    
            SETUP_RETR = 0x04,  
            RF_CH = 0x05,       
            RF_SETUP = 0x06,    
            STATUS = 0x07,      
            OBSERVE_TX = 0x08,  
            RPD = 0x09,         
            RX_ADDR_P0 = 0x0a,  
            RX_ADDR_P1 = 0x0b,  
            RX_ADDR_P2 = 0x0c,  
            RX_ADDR_P3 = 0x0d,  
            RX_ADDR_P4 = 0x0e,  
            RX_ADDR_P5 = 0x0f,  
            TX_ADDR = 0x10,     
            RX_PW_P0 = 0x11,    
            RX_PW_P1 = 0x12,    
            RX_PW_P2 = 0x13,    
            RX_PW_P3 = 0x14,    
            RX_PW_P4 = 0x15,    
            RX_PW_P5 = 0x16,    
            FIFO_STATUS = 0x17, 
            DYNPD = 0x1c,       
            FEATURE = 0x1d      
        };
 
        union observe_tx_t
        {
            uint8_t as_byte; 
 
            struct
            {
                uint8_t arc_cnt : 4;  
                uint8_t plos_cnt : 4; 
            };
 
            explicit observe_tx_t(uint8_t value) INLINE : as_byte{value} {}
        };
 
        union fifo_status_t
        {
            uint8_t as_byte; 
            struct
            {
                bool rx_empty : 1; 
                bool rx_full : 1;  
                uint8_t reserved1 : 2;
                bool tx_empty : 1; 
                bool tx_full : 1;  
                bool tx_reuse : 1; 
                uint8_t reserved2 : 1;
            };
 
            explicit fifo_status_t(uint8_t value) INLINE : as_byte{value} {}
        };
 
        struct addr_t
        {
            uint8_t device;   
            uint16_t network; 
 
            addr_t(uint16_t net, uint8_t dev) INLINE : device{dev}, network{net} {}
        };
 
        enum class State : uint8_t
        {
            POWER_DOWN_STATE = 0,
            STANDBY_STATE,
            RX_STATE,
            TX_STATE
        };
 
        union status_t
        {
            uint8_t as_byte; 
            struct
            {
                bool tx_full : 1; 
                uint8_t rx_p_no : 3; 
                bool max_rt : 1;  
                bool tx_ds : 1;   
                bool rx_dr : 1;   
                uint8_t reserved : 1;
            };
 
            explicit status_t(uint8_t value) INLINE : as_byte{value} {}
        };
 
        // Lowest-level methods to access NRF24L01 device
        uint8_t read(uint8_t cmd)
        {
            this->start_transfer();
            status_ = status_t{this->transfer(cmd)};
            uint8_t result = this->transfer(uint8_t(Command::NOP));
            this->end_transfer();
            return result;
        }
        void write(uint8_t cmd)
        {
            this->start_transfer();
            status_ = status_t{this->transfer(cmd)};
            this->end_transfer();
        }
        void write(uint8_t cmd, uint8_t data)
        {
            this->start_transfer();
            status_ = status_t{this->transfer(cmd)};
            this->transfer(data);
            this->end_transfer();
        }
        void write(uint8_t cmd, const uint8_t* buf, size_t size)
        {
            this->start_transfer();
            status_ = status_t{this->transfer(cmd)};
            this->transfer((uint8_t*) buf, size);
            this->end_transfer();
        }
 
        // Command-level methods to access NRF24L01 device
        uint8_t read_command(Command cmd)
        {
            return read(uint8_t(cmd));
        }
        void write_command(Command cmd)
        {
            write(uint8_t(cmd));
        }
 
        // Mid-level methods to access NRF24L01 device registers
        uint8_t read_register(Register reg)
        {
            return read(uint8_t(Command::R_REGISTER) | uint8_t(uint8_t(Command::REG_MASK) & uint8_t(reg)));
        }
        void write_register(Register reg, uint8_t data)
        {
            write(uint8_t(Command::W_REGISTER) | uint8_t(uint8_t(Command::REG_MASK) & uint8_t(reg)), data);
        }
        void write_register(Register reg, const uint8_t* buf, size_t size)
        {
            write(uint8_t(Command::W_REGISTER) | uint8_t(uint8_t(Command::REG_MASK) & uint8_t(reg)), buf, size);
        }
 
        status_t read_status()
        {
            this->start_transfer();
            status_ = status_t{this->transfer(uint8_t(Command::NOP))};
            this->end_transfer();
            return status_;
        }
 
        void transmit_mode(uint8_t dest);
        void receive_mode();
 
        bool available();
        int read_fifo_payload(uint8_t& src, uint8_t& port, uint8_t* buf, size_t count);
        fifo_status_t read_fifo_status()
        {
            return fifo_status_t{read_register(Register::FIFO_STATUS)};
        }
        observe_tx_t read_observe_tx()
        {
            return observe_tx_t{read_register(Register::OBSERVE_TX)};
        }
 
    private:
        static const uint8_t DEFAULT_CHANNEL = 64;
 
        gpio::FAST_PIN<CE> ce_ = gpio::FAST_PIN<CE>{gpio::PinMode::OUTPUT, false};
 
        addr_t addr_;    
        uint8_t channel_ = DEFAULT_CHANNEL; 
        uint8_t dest_ = 0;  
 
        status_t status_ = status_t{0}; 
        State state_ = State::POWER_DOWN_STATE;  
 
        uint16_t trans_ = 0;   
        uint16_t retrans_ = 0; 
        uint16_t drops_ = 0;   
    };
 
    template<board::DigitalPin CSN, board::DigitalPin CE, board::ExternalInterruptPin IRQ>
    class IRQ_NRF24L01 : public NRF24L01<CSN, CE>
    {
    public:
        IRQ_NRF24L01(uint16_t net, uint8_t dev) : NRF24L01<CSN, CE>{net, dev}
        {
            gpio::FastPinType<board::EXT_PIN<IRQ>()>::set_mode(gpio::PinMode::INPUT_PULLUP);
        }
 
        void begin()
        {
            NRF24L01<CSN, CE>::begin();
            irq_signal_.enable();
        }
 
        void end()
        {
            irq_signal_.disable();
            NRF24L01<CSN, CE>::end();
        }
 
    private:
        interrupt::INTSignal<IRQ> irq_signal_ = interrupt::INTSignal<IRQ>{interrupt::InterruptTrigger::FALLING_EDGE};
    };
 
    template<board::DigitalPin CSN, board::DigitalPin CE>
    NRF24L01<CSN, CE>::NRF24L01(uint16_t net, uint8_t dev) : addr_{net, dev} {}
 
    template<board::DigitalPin CSN, board::DigitalPin CE> void NRF24L01<CSN, CE>::begin()
    {
        using namespace nrf24l01p_internals;
        // Setup hardware features, channel, bitrate, retransmission, dynamic payload
        write_register(Register::FEATURE, (bits::BV8(EN_DPL, EN_ACK_PAY, EN_DYN_ACK)));
        write_register(Register::RF_CH, channel_);
        write_register(Register::RF_SETUP, RF_DR_2MBPS | RF_PWR_0DBM);
        write_register(Register::SETUP_RETR, uint8_t(DEFAULT_ARD << ARD) | uint8_t(DEFAULT_ARC << ARC));
        write_register(Register::DYNPD, DPL_PA);
 
        // Setup hardware receive pipes address; network (16-bit), device (8-bit)
        // P0: auto-acknowledge (see set_transmit_mode)
        // P1: node address<network:device> with auto-acknowledge
        // P2: broadcast<network:0>
        addr_t rx_addr = addr_;
        write_register(Register::SETUP_AW, AW_3BYTES);
        write_register(Register::RX_ADDR_P1, (const uint8_t*) &rx_addr, sizeof(rx_addr));
        write_register(Register::RX_ADDR_P2, BROADCAST);
        write_register(Register::EN_RXADDR, bits::BV8(ERX_P2, ERX_P1));
        write_register(Register::EN_AA, bits::BV8(ENAA_P1, ENAA_P0));
 
        // Ready to go
        powerup();
    }
 
    template<board::DigitalPin CSN, board::DigitalPin CE> void NRF24L01<CSN, CE>::powerup()
    {
        using namespace nrf24l01p_internals;
        if (state_ != State::POWER_DOWN_STATE) return;
        ce_.clear();
 
        // Setup configuration for powerup and clear interrupts
        write_register(Register::CONFIG, bits::BV8(EN_CRC, CRCO, PWR_UP));
        time::delay_ms(Tpd2stby_ms);
        state_ = State::STANDBY_STATE;
 
        // Flush status
        write_register(Register::STATUS, bits::BV8(RX_DR, TX_DS, MAX_RT));
        write_command(Command::FLUSH_TX);
        write_command(Command::FLUSH_RX);
    }
 
    template<board::DigitalPin CSN, board::DigitalPin CE> void NRF24L01<CSN, CE>::standby()
    {
        if (state_ == State::STANDBY_STATE) return;
        ce_.clear();
        state_ = State::STANDBY_STATE;
    }
 
    template<board::DigitalPin CSN, board::DigitalPin CE> void NRF24L01<CSN, CE>::powerdown()
    {
        using namespace nrf24l01p_internals;
        if (state_ == State::POWER_DOWN_STATE) return;
        ce_.clear();
        write_register(Register::CONFIG, bits::BV8(EN_CRC, CRCO));
        state_ = State::POWER_DOWN_STATE;
    }
 
    template<board::DigitalPin CSN, board::DigitalPin CE>
    int NRF24L01<CSN, CE>::send_(uint8_t dest, uint8_t port, const uint8_t* buf, size_t len)
    {
        using namespace nrf24l01p_internals;
        // Note buf == 0 and len == 0 is perfectly acceptable
        if ((buf == nullptr) && (len > 0)) return errors::EINVAL;
        if (len > PAYLOAD_MAX) return errors::EMSGSIZE;
 
        // Setting transmit destination first (needs to ensure standby mode)
        transmit_mode(dest);
 
        // Write source address and payload to the transmit fifo
        Command command = ((dest != BROADCAST) ? Command::W_TX_PAYLOAD : Command::W_TX_PAYLOAD_NO_ACK);
        this->start_transfer();
        status_ = status_t{this->transfer(uint8_t(command))};
        this->transfer(addr_.device);
        this->transfer(port);
        this->transfer(buf, len);
        this->end_transfer();
 
        trans_ += 1;
 
        // Check for auto-acknowledge pipe(0), and address setup and enable
        if (dest != BROADCAST)
        {
            addr_t tx_addr(addr_.network, dest);
            write_register(Register::RX_ADDR_P0, (const uint8_t*) &tx_addr, sizeof(tx_addr));
            write_register(Register::EN_RXADDR, bits::BV8(ERX_P2, ERX_P1, ERX_P0));
        }
 
        // Wait for transmission
        status_t status = status_t{0};
        while (true)
        {
            status = read_status();
            if (status.tx_ds || status.max_rt) break;
            time::yield();
        }
 
        bool data_sent = status.tx_ds;
 
        // Check for auto-acknowledge pipe(0) disable
        if (dest != BROADCAST) write_register(Register::EN_RXADDR, bits::BV8(ERX_P2, ERX_P1));
 
        // Reset status bits
        write_register(Register::STATUS, bits::BV8(TX_DS, MAX_RT));
 
        // Read retransmission counter and update
        observe_tx_t observe = read_observe_tx();
        retrans_ += observe.arc_cnt;
 
        // Check that the message was delivered
        if (data_sent) return len;
 
        // Failed to deliver
        write_command(Command::FLUSH_TX);
        drops_ += 1;
 
        return errors::EIO;
    }
 
    template<board::DigitalPin CSN, board::DigitalPin CE>
    int NRF24L01<CSN, CE>::recv_(uint8_t& src, uint8_t& port, uint8_t* buf, size_t size, uint32_t ms)
    {
        // Run in receive mode
        receive_mode();
 
        // Check if there is data available on any pipe
        uint32_t start = time::millis();
        while (!available())
        {
            if ((ms != 0) && (time::since(start) > ms)) return errors::ETIME;
            time::yield();
        }
 
        // Try and read payload from FIFO
        return read_fifo_payload(src, port, buf, size);
    }
 
    template<board::DigitalPin CSN, board::DigitalPin CE> void NRF24L01<CSN, CE>::set_output_power_level(int8_t dBm)
    {
        using namespace nrf24l01p_internals;
        uint8_t pwr;
        if (dBm < -12)
            pwr = RF_PWR_18DBM;
        else if (dBm < -6)
            pwr = RF_PWR_12DBM;
        else if (dBm < 0)
            pwr = RF_PWR_6DBM;
        else
            pwr = RF_PWR_0DBM;
        write_register(Register::RF_SETUP, RF_DR_2MBPS | pwr);
    }
 
    template<board::DigitalPin CSN, board::DigitalPin CE> void NRF24L01<CSN, CE>::transmit_mode(uint8_t dest)
    {
        using namespace nrf24l01p_internals;
        // Setup primary transmit address
        addr_t tx_addr(addr_.network, dest);
        write_register(Register::TX_ADDR, (const uint8_t*) &tx_addr, sizeof(tx_addr));
 
        // Trigger the transmitter mode
        if (state_ != State::TX_STATE)
        {
            ce_.clear();
            write_register(Register::CONFIG, bits::BV8(EN_CRC, CRCO, PWR_UP));
            ce_.set();
        }
 
        // Wait for the transmitter to become active
        if (state_ == State::STANDBY_STATE) time::delay_us(Tstby2a_us);
        state_ = State::TX_STATE;
    }
 
    template<board::DigitalPin CSN, board::DigitalPin CE> void NRF24L01<CSN, CE>::receive_mode()
    {
        using namespace nrf24l01p_internals;
        // Check already in receive mode
        if (state_ == State::RX_STATE) return;
 
        // Configure primary receiver mode
        write_register(Register::CONFIG, bits::BV8(EN_CRC, CRCO, PWR_UP, PRIM_RX));
        ce_.set();
        if (state_ == State::STANDBY_STATE) time::delay_us(Tstby2a_us);
        state_ = State::RX_STATE;
    }
 
    template<board::DigitalPin CSN, board::DigitalPin CE> bool NRF24L01<CSN, CE>::available()
    {
        // Check the receiver fifo
        if (read_fifo_status().rx_empty) return false;
 
        // Sanity check the size of the payload. Might require a flush
        if (read_command(Command::R_RX_PL_WID) <= DEVICE_PAYLOAD_MAX) return true;
        write_command(Command::FLUSH_RX);
        return false;
    }
 
    template<board::DigitalPin CSN, board::DigitalPin CE>
    int NRF24L01<CSN, CE>::read_fifo_payload(uint8_t& src, uint8_t& port, uint8_t* buf, size_t size)
    {
        // Check for payload error from device (Tab. 20, pp. 51, R_RX_PL_WID)
        uint8_t count = read_command(Command::R_RX_PL_WID) - 2;
        if ((count > PAYLOAD_MAX) || (count > size))
        {
            write_command(Command::FLUSH_RX);
            return errors::EMSGSIZE;
        }
 
        // Data is available, check if this a broadcast or not
        dest_ = (read_status().rx_p_no == 1 ? addr_.device : BROADCAST);
 
        // Read the source address, port and payload
        this->start_transfer();
        status_ = status_t{this->transfer(uint8_t(Command::R_RX_PAYLOAD))};
        src = this->transfer(0);
        port = this->transfer(0);
        this->transfer(buf, count, uint8_t(Command::NOP));
        this->end_transfer();
        return count;
    }
}
 
#endif /* NRF24L01_HH */