STM32LoRaWAN.h

Go to the documentation of this file.

#pragma once
 
#include "Arduino.h"
#include "STM32CubeWL/LoRaWAN/Mac/LoRaMac.h"
#include "BSP/mw_log_conf.h"
#include "BSP/timer_if.h"
#include "STM32RTC.h"
 
 
typedef enum {
  AS923 = LORAMAC_REGION_AS923,
  AU915 = LORAMAC_REGION_AU915,
  CN470 = LORAMAC_REGION_CN470,
  CN779 = LORAMAC_REGION_CN779,
  EU433 = LORAMAC_REGION_EU433,
  EU868 = LORAMAC_REGION_EU868,
  KR920 = LORAMAC_REGION_KR920,
  IN865 = LORAMAC_REGION_IN865,
  US915 = LORAMAC_REGION_US915,
  RU864 = LORAMAC_REGION_RU864,
  // TODO: AU915_TTN = 0x80 | AU915,
} _lora_band;
 
typedef enum {
  RFO = 0,
  PABOOST,
} _rf_mode;
 
// Reuse enum from STM32CubeWL that uses the same names
using _lora_class = DeviceClass_t;
 
class STM32LoRaWAN : public Stream {
  public:
    bool begin(_lora_band band);
 
 
    bool joinOTAA(const char *appEui, const char *appKey, const char *devEui) { return setDevEui(devEui) && joinOTAA(appEui, appKey); }
    bool joinOTAA(const char *appEui, const char *appKey) { return setAppEui(appEui) && setAppKey(appKey) && joinOTAA(); }
    bool joinOTAA(String appEui, String appKey) { return joinOTAA(appEui.c_str(), appKey.c_str()); }
    bool joinOTAA(String appEui, String appKey, String devEui) { return joinOTAA(appEui.c_str(), appKey.c_str(), devEui.c_str()); }
    bool joinOTAA(uint64_t appEui, const char *appKey, uint64_t devEui) { return setDevEui(devEui) && joinOTAA(appEui, appKey); }
    bool joinOTAA(uint64_t appEui, const char *appKey) { return setAppEui(appEui) && setAppKey(appKey) && joinOTAA(); }
    bool joinOTAA(uint64_t appEui, String appKey, uint64_t devEui) { return joinOTAA(appEui, appKey.c_str(), devEui); }
    bool joinOTAA(uint64_t appEui, String appKey) { return joinOTAA(appEui, appKey.c_str()); }
 
    bool joinOTAA();
 
    bool joinABP(const char *devAddr, const char *nwkSKey, const char *appSKey) { return setDevAddr(devAddr) && setNwkSKey(nwkSKey) && setAppSKey(appSKey) && joinABP(); }
    bool joinABP(String devAddr, String nwkSKey, String appSKey) { return joinABP(devAddr.c_str(), nwkSKey.c_str(), appSKey.c_str()); }
    bool joinABP(uint32_t devAddr, String nwkSKey, String appSKey) { return setDevAddr(devAddr) && setNwkSKey(nwkSKey) && setAppSKey(appSKey) && joinABP(); }
 
    bool joinABP();
 
 
    void beginPacket();
    int endPacket(bool confirmed = false);
 
 
    virtual size_t write(uint8_t c);
    virtual size_t write(const uint8_t *buffer, size_t size);
 
    template <typename T> inline size_t write(T val) { return write((uint8_t *)&val, sizeof(T)); };
    using Print::write;
 
    virtual int availableForWrite();
 
    virtual void flush() { }
 
 
 
    int parsePacket();
 
    uint8_t getDownlinkPort() { return rx_port; }
 
    int16_t getDownlinkRssi() { return rx_rssi; }
 
    int8_t getDownlinkSnr() { return rx_snr; }
 
 
    int read(uint8_t *buf, size_t size);
    virtual int available();
    virtual int read();
    virtual int peek();
 
 
    bool setDevEui(const char *value) { return mibSetHex("DevEui", MIB_DEV_EUI, value); }
    bool setDevEui(String value) { return setDevEui(value.c_str()); }
    bool setDevEui(uint64_t value) { return mibSetUint64("DevEui", MIB_DEV_EUI, value); }
    bool setAppEui(const char *value) { return mibSetHex("AppEui", MIB_JOIN_EUI, value); }
    bool setAppEui(String value) { return setAppEui(value.c_str()); }
    bool setAppEui(uint64_t value) { return mibSetUint64("AppEui", MIB_JOIN_EUI, value); }
    bool setDevAddr(const char *value) { return mibSetHex("DevAddr", MIB_DEV_ADDR, value); }
    bool setDevAddr(String value) { return setDevAddr(value.c_str()); }
    bool setDevAddr(uint32_t value) { return mibSetUint32("DevAddr", MIB_DEV_ADDR, value); }
    bool setAppKey(const char *value)
    {
      // In LoRaWAN 1.0, only the appKey was configured and all keys
      // were derived from that. In 1.1, this was split into an appKey
      // and nwkKey. However, when running the LoRaMac-Node in 1.0 mode,
      // it actually seems to use nwkKey, not appKey. So to support
      // sketches that only configure appKey for 1.0, this saves the
      // appKey to nwkKey as well. But to also prepare for future
      // support of 1.1 and sketches that configure both, only do this
      // if no nwkKey was explicitly configured.
      return mibSetHex("AppKey", MIB_APP_KEY, value)
             && (this->nwk_key_set || mibSetHex("NwkKey", MIB_NWK_KEY, value));
 
    }
    bool setAppKey(String value) { return setAppKey(value.c_str()); }
    bool setNwkKey(const char *value)
    {
      this->nwk_key_set = true;
      return mibSetHex("NwkKey", MIB_NWK_KEY, value);
    }
    bool setNwkKey(String value) { return setNwkKey(value.c_str()); }
    bool setAppSKey(const char *value) { return mibSetHex("AppSKey", MIB_APP_S_KEY, value); }
    bool setAppSKey(String value) { return setAppSKey(value.c_str()); }
    bool setNwkSKey(const char *value)
    {
#if (defined( LORAMAC_VERSION ) && ( LORAMAC_VERSION == 0x01010100 ))
      // When compiled for 1.1 crypto, three different keys are used.
      // When the sketch only supplies a single key, just set all
      // three keys to the same value.
      return mibSetHex("NwkSEncKey", MIB_NWK_S_ENC_KEY, value)
             && mibSetHex("FNwkSIntKey", MIB_F_NWK_S_INT_KEY, value)
             && mibSetHex("SNwkSIntKey", MIB_S_NWK_S_INT_KEY, value);
#else /* ( LORAMAC_VERSION == 0x01010100 ) */
      return mibSetHex("NwkSKey", MIB_NWK_S_KEY, value);
#endif /* ( LORAMAC_VERSION == 0x01010100 ) */
    }
    bool setNwkSKey(String value) { return setNwkSKey(value.c_str()); }
 
#if (defined( LORAMAC_VERSION ) && ( LORAMAC_VERSION == 0x01010100 ))
    bool setNwkSEncKey(const char *value) { return mibSetHex("NwkSEncKey", MIB_NWK_S_ENC_KEY, value); }
    bool setNwkSEncKey(String value) { return setNwkSEncKey(value.c_str()); }
    bool setFNwkSIntKey(const char *value) { return mibSetHex("FNwkSIntKey", MIB_F_NWK_S_INT_KEY, value); }
    bool setFNwkSIntKey(String value) { return setFNwkSIntKey(value.c_str()); }
    bool setSNwkSIntKey(const char *value) { return mibSetHex("SNwkSIntKey", MIB_S_NWK_S_INT_KEY, value); }
    bool setSNwkSIntKey(String value) { return setSNwkSIntKey(value.c_str()); }
#endif /* ( LORAMAC_VERSION == 0x01010100 ) */
 
    bool getDevEui(String *value) { return mibGetHex("DevEui", MIB_DEV_EUI, value); }
    bool getDevEui(uint64_t *value) { return mibGetUint64("DevEui", MIB_DEV_EUI, value); }
    bool getAppEui(String *value) { return mibGetHex("AppEui", MIB_JOIN_EUI, value); }
    bool getAppEui(uint64_t *value) { return mibGetUint64("AppEui", MIB_JOIN_EUI, value); }
    bool getDevAddr(String *value) { return mibGetHex("DevAddr", MIB_DEV_ADDR, value); }
    bool getDevAddr(uint32_t *value) { return mibGetUint32("DevAddr", MIB_DEV_ADDR, value); }
 
 
    String deviceEUI();
    String getDevAddr();
 
    bool connected();
 
    bool busy();
 
    operator bool() { return connected(); }
 
 
    bool dataRate(uint8_t dr);
    int getDataRate();
    bool power(uint8_t index);
 
    bool power(_rf_mode mode, uint8_t index) { (void)mode; return power(index); }
 
    bool powerdB(int8_t db);
 
    uint8_t getPort();
    bool setPort(uint8_t port);
 
    bool setADR(bool adr);
    int getADR();
 
 
    bool dutyCycle(bool on);
 
    bool publicNetwork(bool publicNetwork);
 
    int getRX2DR();
    bool setRX2DR(uint8_t dr);
 
    uint32_t getRX2Freq();
    bool setRX2Freq(uint32_t freq);
 
    int getrxfreq();
 
 
    bool enableChannel(unsigned pos);
    bool disableChannel(unsigned pos);
    bool modifyChannelEnabled(unsigned pos, bool value);
    bool isChannelEnabled(unsigned pos);
 
 
    int32_t getFCU();
 
    int32_t getFCD();
 
    [[gnu::error("Not implemented in STM32LoRaWAN")]]
    bool setFCD(uint16_t fcd);
 
    [[gnu::error("Not implemented in STM32LoRaWAN")]]
    bool setFCU(uint16_t fcu);
 
 
 
    bool mibGet(const char *name, Mib_t type, MibRequestConfirm_t &mibReq);
    bool mibGetBool(const char *name, Mib_t type, bool *value);
    bool mibGetUint8(const char *name, Mib_t type, uint8_t *value);
    bool mibGetInt8(const char *name, Mib_t type, int8_t *value);
    bool mibGetUint32(const char *name, Mib_t type, uint32_t *value);
    bool mibGetUint64(const char *name, Mib_t type, uint64_t *value);
    bool mibGetHex(const char *name, Mib_t type, String *value);
    bool mibGetRxChannelParams(const char *name, Mib_t type, RxChannelParams_t *value);
    bool mibGetPtr(const char *name, Mib_t type, void **value);
    bool mibSet(const char *name, Mib_t type, MibRequestConfirm_t &mibReq);
    bool mibSetBool(const char *name, Mib_t type, bool value);
    bool mibSetUint8(const char *name, Mib_t type, uint8_t value);
    bool mibSetInt8(const char *name, Mib_t type, int8_t value);
    bool mibSetUint32(const char *name, Mib_t type, uint32_t value);
    bool mibSetUint64(const char *name, Mib_t type, uint64_t value);
    bool mibSetHex(const char *name, Mib_t type, const char *value);
    bool mibSetRxChannelParams(const char *name, Mib_t type, RxChannelParams_t value);
    bool mibSetPtr(const char *name, Mib_t type, void *value);
    size_t mibHexSize(const char *name, Mib_t type);
 
 
    bool joinOTAAAsync();
 
    int endPacketAsync(bool confirmed = false);
 
    bool send(const uint8_t *payload, size_t size, bool confirmed);
 
    uint8_t lastAck() { return last_tx_acked; }
 
    void maintain();
 
    void maintainUntilIdle();
 
    void setMaintainNeededCallback(std::function<void(void)> callback) { this->maintain_needed_callback = callback; }
 
    void setBatteryLevelCallback(std::function<uint8_t(void)> callback) { this->battery_level_callback = callback; }
 
    bool continuousWave(uint32_t frequency, int8_t powerdBm, uint16_t timeout);
 
    String version() { return "N/A"; }
 
    [[gnu::deprecated("minPollInterval is a no-op on STM32LoRaWAN")]]
    void minPollInterval(unsigned long)
    { }
 
    [[gnu::error("Not implemented in STM32LoRaWAN: confirmed uplinked better handled through endPacket()")]]
    bool setCFM(bool cfm);
 
    [[gnu::error("Not implemented in STM32LoRaWAN: confirmed uplinked better handled through endPacket()")]]
    int getCFM();
 
    [[gnu::error("Not implemented in STM32LoRaWAN: confirmed uplinked better handled through endPacket()")]]
    int getCFS();
 
    [[gnu::error("Not implemented in STM32LoRaWAN: No serial to configure")]]
    bool begin(_lora_band band, uint32_t baud, uint16_t config = SERIAL_8N2);
 
    [[gnu::error("Not implemented in STM32LoRaWAN: No serial to configure")]]
    bool autoBaud(unsigned long timeout = 10000L);
 
    [[gnu::error("Not implemented in STM32LoRaWAN: No serial to configure")]]
    void setBaud(unsigned long baud);
 
    [[gnu::error("Not implemented in STM32LoRaWAN: Test method")]]
    String getTConf();
 
    [[gnu::error("Not implemented in STM32LoRaWAN: Test method")]]
    String setTConf(String params);
 
    [[gnu::error("Not implemented in STM32LoRaWAN: Test method")]]
    bool enTtone();
 
    [[gnu::error("Not implemented in STM32LoRaWAN: No remote module to restart")]]
    bool restart();
 
    [[gnu::error("Not implemented in STM32LoRaWAN: No remote module to poll")]]
    void poll();
 
    [[gnu::error("Not implemented in STM32LoRaWAN: No remote module to sleep")]]
    bool sleep(bool on = true);
 
    [[gnu::error("Not implemented in STM32LoRaWAN: No remote module to reset")]]
    bool factoryDefault();
 
    [[gnu::error("Not implemented in STM32LoRaWAN: No protocol stream to configure")]]
    bool format(bool hexMode);
 
    [[gnu::error("Not implemented in STM32LoRaWAN: No protocol stream to configure")]]
    void dumb();
 
    [[gnu::error("Not implemented in STM32LoRaWAN: Internal method in MKRWAN")]]
    bool init();
 
    [[gnu::error("Not implemented in STM32LoRaWAN: Only class A supported")]]
    bool configureClass(_lora_class _class);
 
    [[gnu::error("Not implemented in STM32LoRaWAN: Keys cannot be retrieved")]]
    String getNwkSKey();
 
    [[gnu::error("Not implemented in STM32LoRaWAN: Keys cannot be retrieved")]]
    String getAppSKey();
 
    [[gnu::error("Not implemented in STM32LoRaWAN: Keys cannot be retrieved")]]
    String applicationKey();
 
    [[gnu::error("Not implemented in STM32LoRaWAN: Internal method in MKRWAN (use enableChannel/disableChannel instead)")]]
    bool sendMask(String newMask);
 
    [[gnu::error("Not implemented in STM32LoRaWAN: Internal method in MKRWAN (use enableChannel/disableChannel instead)")]]
    bool sendMask();
 
    [[gnu::error("Not implemented in STM32LoRaWAN: Internal method in MKRWAN (use enableChannel/disableChannel instead)")]]
    String getChannelMask();
 
    [[gnu::error("Not implemented in STM32LoRaWAN: Internal method in MKRWAN (use enableChannel/disableChannel instead)")]]
    int getChannelMaskSize(_lora_band band);
 
    [[gnu::error("Not implemented in STM32LoRaWAN: Changing band after initialization not supported")]]
    bool configureBand(_lora_band band);
 
  protected:
    static void MacMcpsConfirm(McpsConfirm_t *McpsConfirm);
    static void MacMcpsIndication(McpsIndication_t *McpsIndication, LoRaMacRxStatus_t *RxStatus);
    static void MacMlmeConfirm(MlmeConfirm_t *MlmeConfirm);
    static void MacMlmeIndication(MlmeIndication_t *MlmeIndication, LoRaMacRxStatus_t *RxStatus);
    static void MacProcessNotify();
    static uint8_t GetBatteryLevel();
 
    static STM32LoRaWAN *instance;
 
    LoRaMacPrimitives_t LoRaMacPrimitives = {
      .MacMcpsConfirm = MacMcpsConfirm,
      .MacMcpsIndication = MacMcpsIndication,
      .MacMlmeConfirm = MacMlmeConfirm,
      .MacMlmeIndication = MacMlmeIndication,
    };
 
    LoRaMacCallback_t LoRaMacCallbacks = {
      .GetBatteryLevel = GetBatteryLevel,
      .GetTemperatureLevel = nullptr,
      .GetUniqueId = nullptr, // Not needed, we just explicitly set the deveui in begin()
      .GetDevAddress = nullptr, // Not needed, user explicitly configures devaddr
      .NvmDataChange = nullptr,
      .MacProcessNotify = MacProcessNotify,
    };
 
    uint64_t builtinDevEUI();
 
    static const char *toString(LoRaMacStatus_t);
    static const char *toString(LoRaMacEventInfoStatus_t);
    static const char *toString(Mlme_t);
    static const char *toString(Mcps_t);
 
    static uint8_t parseHex(char c);
    static bool parseHex(uint8_t *dest, const char *hex, size_t dest_len);
    static char toHex(uint8_t b);
    static bool toHex(String *dest, const uint8_t *src, size_t src_len);
 
    static uint32_t makeUint32(uint8_t a, uint8_t b, uint8_t c, uint8_t d) { return (uint32_t)a << 24 | (uint32_t)b << 16 | (uint32_t)c << 8 | (uint32_t)d << 0; }
 
    static bool failure(const char *fmt, ...)
    __attribute__((format(printf, 1, 2)));
 
    void clear_rx() { rx_ptr = rx_buf + sizeof(rx_buf); }
 
    void add_rx(const uint8_t *buf, size_t len);
 
    uint8_t tx_dr = DR_4;
 
    uint8_t tx_port = 2;
 
    uint8_t rx_port = 0;
 
    int16_t rx_rssi = 0;
 
    int8_t rx_snr = 0;
 
    bool nwk_key_set = false;
 
    // Buffer sizes match LORAMAC_PHY_MAXPAYLOAD (but that is not
    // public).
    uint8_t tx_buf[255];
    uint8_t *tx_ptr;
    uint8_t rx_buf[255];
    uint8_t *rx_ptr;
 
    bool last_tx_acked = false;
    uint32_t fcnt_up = 0;
    uint32_t fcnt_down = 0;
 
    std::function<void(void)> maintain_needed_callback;
    std::function<uint8_t(void)> battery_level_callback;
 
    bool mac_process_pending = false;
 
    static constexpr uint32_t DEFAULT_JOIN_TIMEOUT = 60000;
};
// For MKRWAN compatibility
using LoRaModem = STM32LoRaWAN;