beacon.hpp

Go to the documentation of this file.

/* SPDX-License-Identifier: Apache-2.0 */
/* Copyright 2018-2019 Peter A. Bigot */
 
#ifndef NRFCXX_SD_BEACON
#define NRFCXX_SD_BEACON
#pragma once
 
#include <pabigot/ble/gap.hpp>
 
#include <nrfcxx/clock.hpp>
 
#include "ble.h"
 
namespace nrfcxx {
namespace sd {
 
class Beacon
{
  struct ref_next
  {
    using pointer_type = Beacon*;
    pointer_type& operator() (Beacon& bcn) noexcept
    {
      return bcn.next_ready_;
    }
  };
 
  using queue_type = pabigot::container::forward_chain<Beacon, ref_next>;
 
public:
  using crc_type = uint16_t;
 
  static constexpr size_t MAX_MSD_LENGTH = 19 + sizeof(crc_type);
 
  enum state_e : uint8_t
  {
    INVALID = 0,
 
    FAILED,
 
    INACTIVE,
 
    CANCELLED,
 
    SCHEDULED_PREPARE,
 
    SCHEDULED,
 
    READY,
 
    ACTIVE,
  };
 
  struct telemetry_state_type
  {
    uint64_t total_uptime;
 
    unsigned int previous_adv;
 
    unsigned int current_adv;
 
    uint32_t adv_cnt () const
    {
      return current_adv;
    }
 
    uint32_t aggr_adv_cnt () const
    {
      return previous_adv + current_adv;
    }
 
    uint32_t sec_cnt () const
    {
      using clock::uptime;
      return (10 * uptime::now()) / uptime::Frequency_Hz;
    }
 
    uint32_t aggr_sec_cnt () const
    {
      using clock::uptime;
      return (10 * (total_uptime + uptime::now())) / uptime::Frequency_Hz;
    }
  };
 
  static const telemetry_state_type& telemetry_state ()
  {
    return telemetry_state_;
  }
 
  static constexpr uint16_t COMPANY_ID = -1;
 
  static constexpr uint8_t APP_FRAME_TYPE_BASE = 0x80;
 
  static constexpr uint8_t APP_FRAME_TYPE_LIMIT = 0xEF;
 
  static constexpr uint8_t FRAME_TYPE_TEST = 0xFF;
 
  struct frame_prefix_s
  {
    uint8_t frame_type = FRAME_TYPE_TEST;
 
    uint8_t flags = 0;
  } __attribute__((__packed__));
 
  /* You can't move or copy these because that would invalidate the
   * links in the ready queue. */
  Beacon (const Beacon&) = delete;
  Beacon& operator= (const Beacon&) = delete;
  Beacon (Beacon&&) = delete;
  Beacon& operator= (Beacon&&) = delete;
  virtual ~Beacon ();
 
  state_e state () const
  {
    return state_;
  }
 
  int validate () const;
 
  unsigned int min_interval_utt () const
  {
    return min_interval_;
  }
 
  unsigned int interval_utt () const
  {
    return interval_;
  }
 
  unsigned int max_interval_utt () const
  {
    return max_interval_;
  }
 
  unsigned int prepare_backoff_utt () const
  {
    return prepare_backoff_;
  }
 
  int set_interval (unsigned int utt)
  {
    return set_interval(utt, utt);
  }
 
  int set_interval (unsigned int min_utt,
                    unsigned int max_utt);
 
  int set_prepare_backoff (notifier_type notify,
                           unsigned int backoff_utt);
 
  void set_tx_notify (notifier_type notify)
  {
    tx_notify_ = notify;
  }
 
  uint8_t dt_flags () const
  {
    return dt_flags_;
  }
 
  void dt_flags (uint8_t v);
 
  int8_t dt_tx_power () const
  {
    return dt_tx_power_;
  }
 
  void dt_tx_power (int8_t v);
 
  int reset_interval ();
 
  int activate ();
 
  int deactivate ();
 
  unsigned int tx_count () const
  {
    return tx_count_;
  }
 
  template <typename FT>
  crc_type update_crc (FT * bp)
  {
    return update_crc_(reinterpret_cast<uint8_t*>(bp), sizeof (*bp));
  }
 
  static const Beacon* active ()
  {
    return active_;
  }
 
  static void set_notify (notifier_type notify);
 
  static int process_event ();
 
  static int process_completion ();
 
  static void telemetry_state_setup (const systemState::state_type& ss,
                                     bool is_reset,
                                     bool retained);
 
protected:
  Beacon ();
 
  virtual int pre_activate_ ()
  {
    return 0;
  }
 
  crc_type update_crc_ (uint8_t* sp, size_t span);
 
  virtual int populate_ (pabigot::ble::gap::adv_data& ad)
  {
    return -EINVAL;
  }
 
private:
  static bool alarm_callback (clock::alarm& alarm);
 
  static void requeue_active_ ();
 
  static notifier_type notify_;
 
  static Beacon* active_;
 
  static queue_type readyq_;
 
  static telemetry_state_type telemetry_state_;
 
  static void checked_notify_ ();
 
  Beacon* reschedule_ ();
 
  clock::alarm alarm_;
 
  notifier_type prepare_notify_;
  notifier_type tx_notify_;
  unsigned int tx_count_ = 0;
 
  unsigned int interval_ = 0;
  unsigned int min_interval_ = 0;
  unsigned int max_interval_ = 0;
  unsigned int prepare_backoff_ = 0;
 
  unsigned int last_due_ = 0;
 
  queue_type::pointer_type next_ready_ = queue_type::unlinked_ptr();
 
  state_e volatile state_ = INVALID;
  uint8_t dt_flags_ = pabigot::ble::gap::FDT_LE_NON_DISCOVERABLE;
  int8_t dt_tx_power_ = 0;
 
  /* Although S130 will store the PDU in SD RAM, S132 appears to
   * transmit from an application-owned buffer.  Have the beacon
   * instance own the data regardless of soft device. */
  std::array<uint8_t, pabigot::ble::gap::ASR_DATA_SIZE> pdu_;
 
#if (NRFCXX_SOFTDEVICE_IS_S130 - 0)
#elif ((NRFCXX_SOFTDEVICE_IS_S132 - 0) || (NRFCXX_SOFTDEVICE_IS_S140 - 0))
  /* S132 and S140 use a handle to identify the advertising set
   * characteristics, but contrary to the implication you can only
   * define one advertising set.
   *
   * See https://devzone.nordicsemi.com/f/nordic-q-a/35200/sd_ble_gap_adv_set_configure-returning-error-4-nrf_error_no_mem */
  static uint8_t handle_;
#else // NRFCXX_SOFTDEVICE_IS_
#error softdevice not supported
#endif // NRFCXX_SOFTDEVICE_IS_
};
 
template <typename CONTENT_TYPE,
          uint8_t ID>
class GenericBeacon : public nrfcxx::sd::Beacon
{
public:
  using content_type = CONTENT_TYPE;
  static constexpr uint8_t FRAME_TYPE = ID;
  static constexpr size_t content_span = CONTENT_TYPE::SPAN;
 
  struct frame_s
  {
    frame_prefix_s prefix;
 
    uint8_t content[0];
  } __attribute__((__packed__));
 
  content_type content{};
 
  uint8_t flags = 0;
 
  bool ready = false;
 
protected:
  int populate_ (pabigot::ble::gap::adv_data& ad) override
  {
    static_assert(content_span <= sizeof(content_type),
                  "span overruns content");
    if (!ready) {
      return 0;
    }
    auto beacon_span = sizeof(frame_s) + content_span;
    auto bp = static_cast<frame_s *>(ad.set_ManufacturerSpecificData(COMPANY_ID, beacon_span));
    if (bp) {
      bp->prefix = {FRAME_TYPE, flags};
      memcpy(bp->content, &content, content_span);
    }
    return 1;
  }
};
 
class TelemetryBeacon : public Beacon
{
public:
  static constexpr uint8_t FRAME_TYPE = 0;
 
  typedef unsigned int (* power_level_type) (unsigned int);
 
  enum frame_flag_e : uint8_t
  {
    FT_FLAG_MAINS_POWER = 0x01,
 
    FT_FLAG_PWR_IS_Vdd = 0x02,
 
    FT_FLAG_CHARGING = 0x04,
 
    FT_FLAG_AGGREGATE_UPTIME = 0x08,
 
    FT_FLAG_HAS_POWER_LEVEL = 0x10,
 
    FT_FLAG_HAS_RESET_COUNT = 0x20,
 
    //
    // Bits 6-7 are undefined and should be zero.
  };
 
  struct frame_s
  {
    frame_prefix_s prefix;
 
    uint16_t pwr_mV;
 
    uint32_t adv_cnt;
 
    uint32_t sec_cnt;
 
    uint16_t reset_cnt;
 
    uint16_t sleep_n16;
 
    uint16_t radio_n16;
 
    uint8_t optional[0];
  } __attribute__((__packed__));
 
  TelemetryBeacon (const systemState& system_state);
 
  const systemState& system_state;
 
  void update_pwr_mV (uint16_t pwr_mV,
                      bool is_vdd = false)
  {
    pwr_mV_ = pwr_mV;
    if (is_vdd) {
      mutate_flags(FT_FLAG_PWR_IS_Vdd, 0);
    } else {
      mutate_flags(0, FT_FLAG_PWR_IS_Vdd);
    }
  }
 
  uint8_t mutate_flags (uint8_t set,
                        uint8_t clear)
  {
    flags_ = set | (flags_ & ~clear);
    return flags_;
  }
 
  void power_level (power_level_type fn)
  {
    power_level_ = fn;
  }
 
private:
  int populate_ (pabigot::ble::gap::adv_data& ad) override;
  power_level_type power_level_{};
  uint16_t pwr_mV_ = 0;
  uint8_t flags_ = 0;
};
 
class SystemStateBeacon : public Beacon
{
public:
  static constexpr uint8_t FRAME_TYPE = 1;
 
  struct frame_s
  {
    frame_prefix_s prefix;
 
    uint32_t last_pc;             
    uint32_t code;                
    uint32_t sdfault_id;          
    uint16_t reset_count;         
    uint16_t reset_reas;          
    uint8_t wdt_status;           
 
    uint8_t heap_use;
 
    uint8_t stack_use;
  } __attribute__((__packed__));
 
  SystemStateBeacon (const systemState& system_state);
 
  const systemState& system_state;
 
private:
  int populate_ (pabigot::ble::gap::adv_data& ad) override;
};
 
class EnvSensorBeacon : public nrfcxx::sd::Beacon
{
public:
  static constexpr uint8_t FRAME_TYPE = 2;
 
  enum frame_flag_e : uint8_t
  {
    FT_FLAG_TEMPERATURE = 0x01,
 
    FT_FLAG_HUMIDITY = 0x02,
 
    FT_FLAG_ABS_PRESSURE = 0x04,
 
    FT_FLAG_DIFF_PRESSURE = 0x08,
 
    FT_FLAG_IAQ_ECO2 = 0x10,
 
    FT_FLAG_IAQ_ETVOC = 0x20,
 
    FT_FLAG_LIGHT_INTENSITY = 0x40,
  };
 
  using frame_s = frame_prefix_s;
 
  struct instance_s
  {
    std::array<uint8_t, MAX_MSD_LENGTH> buffer;
 
    uint8_t span;
  };
 
  struct threshold_s
  {
    uint16_t temperature_cCel;
 
    uint16_t humidity_pptt;
 
    uint32_t abs_cPa;
 
    uint16_t diff_cPa;
 
    uint16_t eCO2_ppm;
 
    uint16_t eTVOC_ppb;
 
    uint8_t light_1;
  };
 
  int significantChange (const instance_s& from,
                         const threshold_s& thr) const;
 
  const instance_s& instance () const
  {
    return instance_;
  }
 
  EnvSensorBeacon ();
 
  EnvSensorBeacon& resetInstance ();
  EnvSensorBeacon& addTemperature (int16_t value_cCel);
  EnvSensorBeacon& addHumidity (uint16_t value_pptt);
  EnvSensorBeacon& addAbsPressure (unsigned int value_cPa);
  EnvSensorBeacon& addDiffPressure (int16_t value_cPa);
  EnvSensorBeacon& addECO2 (uint16_t value_ppm);
  EnvSensorBeacon& addETVOC (uint16_t value_ppb);
  EnvSensorBeacon& addLightIntensity (uint8_t value_1);
  EnvSensorBeacon& addThermistor (int16_t value_cCel);
  int finalizeInstance();
 
private:
  bool append_ (const void* vp, size_t len);
 
  void setFlag_ (uint8_t flag)
  {
    auto fp = reinterpret_cast<frame_s *>(instance_.buffer.data());
    if (fp->flags & (~(flag - 1))) {
      nrfcxx::failsafe(nrfcxx::FailSafeCode::API_VIOLATION);
    }
    fp->flags |= flag;
  }
 
  instance_s instance_;
 
  uint8_t bi_ = 0;
 
  int populate_ (pabigot::ble::gap::adv_data& ad) override;
};
 
class ApplicationIdBeacon : public Beacon
{
public:
  static constexpr uint8_t FRAME_TYPE = 3;
 
  struct frame_s
  {
    frame_prefix_s prefix;
 
    uint32_t app_crc;
 
    uint16_t sd_fwid;
 
    uint8_t llver;
 
    uint8_t stack_KiBy;
 
    uint8_t heap_KiBy;
 
  } __attribute__((__packed__));
 
  ApplicationIdBeacon ();
 
  void prepare (const systemState& system_state,
                const ble_version_t& fwid);
 
private:
  int pre_activate_ () override;
 
  frame_s frame_;
  int populate_ (pabigot::ble::gap::adv_data& ad) override;
};
 
} // namespace sd
} // namespace nrfcxx
 
#endif /* NRFCXX_SD_BEACON */