mysensors_base.h

Go to the documentation of this file.

/*
 * mysensors_base.h
 *
 * The base definition/declaration for sensors, global control variables and sensor availability
 *
 *  Created on: 29. 1. 2026
 *      Author: Milan
 */
 
#ifndef INC_MYSENSORS_BASE_H_
#define INC_MYSENSORS_BASE_H_
 
#include "mysensors_def.h"
 
#include "tmphm_sht45.h"
#include "amb_tsl2591.h"
#include "bar_ils22qs.h"
#include "bar_bmp585.h"
#include "scd41.h"
#include "sps30.h"
 
#include <stdint.h>
 
#pragma pack(1)
/** @brief 4-byte ASCII signature stored at offset 0 of systemParams_t to validate data integrity. */
#define SYSTEMPARAMS_SIGN "MTTV"
 
/** @brief Total size in bytes of the systemParams_t structure stored on the NFC tag and send via LoRa - the size is used for check of struct  systemParams_t
 * and it doens't match, the Error_Handler() is called
 */
#define SZ_SYSTEMPARAMS 90
 
/** @brief Version of the systemParams_t layout; increment when fields are added or reordered. */
#define SYSTEMPARAMS_STRUCTVER 1
 
/** @brief Application firmware minor version number (plain integer). */
#define SYSTEMPARAMS_APPVER00 0x01
 
/** @brief Application firmware major version number (plain integer) - check of validity struct together with SYSTEMPARAMS_SIGN. */
#define SYSTEMPARAMS_APPVER01 0x01
 
/** @brief The default sensor altitue */
#define SYSTEMPARAMS_DEFAULTALTITUDE 300
 
/** @brief Minimum allowed sensor measurement interval in milliseconds (30 seconds). */
#define SYSTEMPARAMS_MINSENSORTIME 30000
 
/** @brief Default sensor measurement interval in milliseconds (10 minutes). */
#define SYSTEMPARAMS_DEFAULTSENSORTIME 60*1000*10
 
/** @brief Maximum allowed sensor measurement interval in milliseconds (18 hour). */
#define SYSTEMPARAMS_MAXSENSORTIME 60*1000*60*18
 
/**
 * @brief Minimum idle time in milliseconds before the device enters OFF (standby) mode.
 *        Values below ~10 s are too short because the LoRaWAN stack may still be
 *        finishing a transmission when the timer fires.
 */
#define SYSTEMPARAMS_MINTIME2OFF 10000
 
 
/** @brief Minimum valid LoRaWAN application port number (port 0 is reserved by the stack). */
#define SYSTEMPARAMS_MINLORAWANPORT 1
 
/** @brief Default LoRaWAN application port used for sensor uplinks. */
#define SYSTEMPARAMS_DEFAULTLORAWANPORT 2
 
/** @brief Maximum valid LoRaWAN application port number (ports 224–255 are reserved). */
#define SYSTEMPARAMS_MAXLORAWANPORT 223
 
 
/** @brief Default LoRaWAN JoinEUI / AppEUI (8 bytes, all zeros – overridden via NFC). */
#define SYSTEM_APP_EUI                  00,00,00,00,00,00,00,00
 
/** @brief Default LoRaWAN AppKey (16 bytes – overridden via NFC before deployment). */
#define SYSTEM_APP_KEY                  AB,CD,EF,01,02,03,10,11,12,05,06,07,EF,EF,EF,EF
 
/** @brief First byte of the 3-byte OUI prefix used in the auto-generated DevEUI. */
#define SYSTEM_APP_DevEUI0 0x45
/** @brief Second byte of the 3-byte OUI prefix used in the auto-generated DevEUI. */
#define SYSTEM_APP_DevEUI1 0x87
/** @brief Third byte of the 3-byte OUI prefix used in the auto-generated DevEUI. */
#define SYSTEM_APP_DevEUI2 0xF2
 
/*
 * The DevEUI is defined as fixed 3 bytes and CRC to identify of Amica RAK devices
 * [ 45 87 F2 ] [ uid_4bytes ] [ crc8 ]
 *    0   1   2    3  4  5  6      7
 *
 *
 *  The first 3 bytes of a DevEUI in LoRaWAN are typically an IEEE OUI (Organizationally Unique Identifier).
 *  Using a random value like 4587F2 risks colliding with a registered vendor. For example, 45:87:F2 may already belong to someone.
 *
 *  Options:
 *      Register your own OUI with IEEE (~$730 USD, gives you a block of 4096+ EUIs) — overkill for most projects.
 *      Use the locally-administered bit — set bit 1 of byte 0 (0x02 mask), which signals "this is locally assigned, not globally unique."
 *      Example: 46 87 F2 (note 46 has bit 1 set). This is the standard way to signal a private/local identifier.
 *      Keep 4587F2 if this is purely internal/private LoRaWAN (no public network, no TTN/Helium), since collisions don't matter in a closed network.
 *
 *  if (DevEUI[0] == 0x45 && DevEUI[1] == 0x87 && DevEUI[2] == F2 && systemParams_CalculateCrc(DevEUI, 7) == DevEUI[7])
 *  {
 *  }
 */
 
/**
 * @brief Bitmask of sensor modules that are enabled / available for data collection.
 *        Used in systemParams_t.AvailableSensors; individual bits can be ORed together.
 */
typedef enum
{
    SYSPARAM_TEMP_HUM    = 0x01,    /**< Temperature and humidity sensor (SHT45) */
    SYSPARAM_BAR         = 0x02,    /**< Barometric pressure sensor (ILPS22QS or BMP585) */
    SYSPARAM_AMBIENT     = 0x04,    /**< Ambient light sensor (TSL2591) */
    SYSPARAM_CO2         = 0x08,    /**< CO2 / temperature / humidity sensor (SCD41) */
    SYSPARAM_PARTICULAR  = 0x10     /**< Particular matter sensor (SPS30) */
} systemParams_Sensors_t;
 
/**
 * @brief System configuration parameters – persisted in NFC EEPROM at address 0.
 * The structure contains all modifiable variables/settings of system, can be read/writa via NFC tool or LoRa special read/write process
 * The structure is 90 bytes (SZ_SYSTEMPARAMS) with a CRC8 byte at the end.
 * Fields marked RO are written by the firmware; fields marked RW can be updated by a phone app via the NFC EEPROM or via LoRa special process
 *
 * The following code is used for checking the structure validity:
 * @code
 * if (strcmp(_systemParams.Sign, SYSTEMPARAMS_SIGN) != 0 || _systemParams.AppVersion[1] != SYSTEMPARAMS_APPVER01)
 * {
 *  .... the structure is not valid
 * }
 *
 * // crc checking
 *  if (!systemParams_CheckCRC(&_systemParams))
 *  {
 *  .... the structure is not valid
 *  }
 *
 * @endcode
 *
 * @note Do not reorder fields – the phone app and MQTT server rely fixed offsets.
 */
typedef struct
{
    /**< header - identification of structure, sign & version */
    char Sign[5];                    /**< RO  Magic signature "MTTV" – used to detect uninitialized memory */
    uint8_t AppVersion[2];           /**< RO  Firmware version bytes [major, minor] (see SYSTEMPARAMS_APPVER00/01) */
    /**< ---------------------------------------------------- */
 
    /**< sensor settings  */
    uint32_t SensTimeoutMeasure;     /**< RW  Sensor measurement interval in ms (min 30 s, default 10 min, max 18 h) */
    uint16_t SensAltitude;           /**< RW  Elevation above sea level in metres used for sea-level pressure correction */
    uint8_t SensSendInOnePacket;     /**< RW  1 – pack all sensor values into one uplink; 0 – send separately (default 0) */
    uint8_t SensAvailableSensors;    /**< RW  Bitmask of sensors to poll (see systemParams_Sensors_t); default 0x1F (all) */
    /**< ---------------------------------------------------- */
 
    /**< memory settings */
    uint8_t MemsStoreSensorData;         /**< RW  1 – store readings in external flash; 0 – transmit only (default 1) */
    uint16_t MemsMaxSensorData;          /**< RO  Maximum number of sensor records the flash circular queue can hold */
    uint16_t MemsCurrentCountSensorData; /**< RO  Number of sensor records currently stored in the queue */
    /**< ---------------------------------------------------- */
 
    /**< LoRaWan settings */
    uint8_t LoRaPort;                  /**< RW  LoRaWAN uplink port (min 1, default 2, max 223; ports ≥224 are reserved) */
    uint8_t LoRaRepeatTryConnect;      /**< RW  Number of join retries after duty-cycle back-off (default 10, max 20) */
    uint8_t LoRaAdaptiveDataRate;      /**< RW  1 – enable ADR (DataRate field is then ignored); 0 – fixed DR (default 1) */
    uint8_t LoRaDataRate;              /**< RW  Fixed data rate when ADR is disabled (0=DR_0 slowest … 5=DR_5 fastest) */
    uint8_t LoRaTxPower;               /**< RW  TX power index (0=max power … 7=min power, default 0) */
    uint8_t LoRaClass;                 /**< RW  LoRaWAN device class: 0=Class A (default), 1=Class B, 2=Class C */
    uint8_t LoRaRegion;                /**< RW  LoRaWAN region index (default 5 = EU868; range 0–9) */
    /**< ---------------------------------------------------- */
 
    /**< hardware settings */
    uint8_t HWBatteryLevelStatus;      /**< RO  Battery charge level on a 1–254 scale (1 = very low, 254 = full) */
    uint16_t HWBatteryMV;              /**< RO  Battery voltage in millivolts */
    uint8_t HWDevEUI[8];               /**< RO  DevEUI derived from chip UID (format: [45 87 F2][4-byte UID][crc8]) */
    uint8_t HWAppEUI[8];               /**< RW  LoRaWAN JoinEUI / AppEUI (default: all zeros) */
    uint8_t HWAppKEY[16];              /**< RW  LoRaWAN AppKey used for OTAA join (change before deployment) */
    uint32_t HWDevADDR;                /**< RO  LoRaWAN DevAddr assigned after a successful OTAA join */
    /**< ---------------------------------------------------- */
 
    /**< device settings */
    uint8_t DevRestart;                 /**< RW  Write 1 from phone app to trigger a software restart on next poll */
    uint8_t DevReset;                   /**< RW  Write 1 from phone app to reset to factory defaults on next poll */
    uint8_t DevOnOff;                   /**< RW  0 – device wakes periodically by RTC timer; 1 – stay on (default 0) */
    /**< ---------------------------------------------------- */
 
    /**< dummy */
    uint8_t Dummy[20];               /**< RW  Reserved for future use; initialised to 0 */
    /* ------ CRC covers all fields above; Crc itself is excluded from the calculation */
    uint8_t Crc;                     /**< CRC8 of bytes 0..(SZ_SYSTEMPARAMS-2); must be the last field */
} systemParams_t;
#pragma pack()
 
extern int8_t _tryInit;         /**< Flag used by xxx_Is() calls; when set to 1, the Is function attempts to (re-)initialise the sensor */
extern systemParams_t _systemParams;    /**< Global system parameters read from / written to the NFC tag EEPROM */
 
 
/**
 * @brief Return a pointer to the DevEUI stored in _systemParams.
 *        The DevEUI is auto-generated from the chip UID during initialisation
 *        and is read-only from the phone app's perspective.
 * @return Pointer to the 8-byte DevEUI array inside _systemParams.
 */
uint8_t* systemParams_getAppDevEUI();
 
/**
 * @brief Return a pointer to the AppEUI (JoinEUI) stored in _systemParams.
 *        Used by the LoRaWAN stack during the OTAA join procedure.
 * @return Pointer to the 8-byte AppEUI array inside _systemParams.
 */
uint8_t* systemParams_getAppEUI();
 
/**
 * @brief Return a pointer to the AppKey stored in _systemParams.
 *        Used by the LoRaWAN stack to derive session keys during OTAA join.
 * @return Pointer to the 16-byte AppKey array inside _systemParams.
 */
uint8_t* systemParams_getAppKey();
 
 
/**
 * @brief Calculate a CRC-8 checksum (Sensirion polynomial) over a byte buffer.
 *        Used to validate sensor I2C response packets as well as the CRC field
 *        of systemParams_t.
 * @param data Pointer to the data buffer.
 * @param len  Number of bytes to include in the calculation.
 * @return Computed CRC-8 byte.
 */
uint8_t systemParams_CalculateCrc(uint8_t* data, uint8_t len);
 
/**
 * @brief Verify the CRC field of a systemParams_t structure.
 * @param par Pointer to the systemParams_t to check.
 * @retval 1 – CRC is valid (structure is intact).
 * @retval 0 – CRC mismatch (structure is corrupt or uninitialised).
 */
uint8_t systemParams_CheckCRC(const systemParams_t* par);
 
/**
 * @brief Recalculate and store the CRC in _systemParams.Crc.
 *        Call this after modifying any field of _systemParams before writing
 *        the structure to the NFC EEPROM.
 */
void systemParams_SetCRCSystemParams();
 
/**
 * @brief Clamp all RW fields of _systemParams to their valid ranges.
 *        Called after loading parameters from NFC to ensure no out-of-range
 *        values are used (e.g. port numbers, timeouts, data rates).
 */
void systemParams_Correction();
 
/**
 * @brief Check whether a particular sensor is enabled in _systemParams.AvailableSensors.
 * @param sensorType One of the systemParams_Sensors_t bitmask values.
 * @retval 1 – sensor is marked as available and should be polled.
 * @retval 0 – sensor is disabled in the configuration.
 */
uint8_t systemParams_IsSensorAvaiable(systemParams_Sensors_t sensorType);
 
 
 
#ifdef WRITELOG
/**
 * @brief Log the current _systemParams fields to the UART debug output.
 * @param info Optional prefix string printed before the dump (e.g. "LOAD" or "SAVE").
 */
void systemParams_Log(const char* info);
#else
#define systemParams_Log(...)
#endif
 
 
/**
 * @defgroup SensorSizes Per-sensor payload size helpers
 * @{
 * Each macro evaluates to sizeof(sensor_data_struct) when the corresponding
 * sensor is enabled, or 0 when it is disabled.  Used to compute SENSORS_DATASIZE.
 */
#ifdef SENSOR_SHT45
    /** @brief Byte size of tmphm_sht45_t in the packed sensor record. */
    #define SIZE_SHT45  sizeof(tmphm_sht45_t)
#else
    #define SIZE_SHT45  0
#endif
 
#ifdef SENSOR_AMB_TSL2591
    /** @brief Byte size of amb_tsl2591_t in the packed sensor record. */
    #define SIZE_TSL2591    sizeof(amb_tsl2591_t)
#else
    #define SIZE_TSL2591    0
#endif
 
#ifdef SENSOR_BAR_ILS22QS
    /** @brief Byte size of bar_ils22qs_t in the packed sensor record. */
    #define SIZE_ILS22QS    sizeof(bar_ils22qs_t)
#else
    #define SIZE_ILS22QS    0
#endif
 
#ifdef SENSOR_BAR_BMP585
    /** @brief Byte size of bar_bmp585_t in the packed sensor record. */
    #define SIZE_BMP585 sizeof(bar_bmp585_t)
#else
    #define SIZE_BMP585 0
#endif
 
#ifdef SENSOR_SCD41
    /** @brief Byte size of scd41_t in the packed sensor record. */
    #define SIZE_SCD41  sizeof(scd41_t)
#else
    #define SIZE_SCD41  0
#endif
 
#ifdef SENSOR_SPS30
    /** @brief Byte size of sps30_t in the packed sensor record. */
    #define SIZE_SPS30  sizeof(sps30_t)
#else
    #define SIZE_SPS30  0
#endif
/** @} */
 
/**
 * @brief Total size in bytes of one packed sensor data record.
 *        Computed as the sum of all enabled sensor struct sizes.
 *        Stored as Data_ItemSize in mems_MainBlock_t; changing the set of
 *        active sensors changes this value and requires a memory reset.
 *        The struct size contains 2bytes - represent the timeout of sensor measuring, in 0.1minutes (10min -> value 100, 0.5min value 50)
 */
#define SENSORS_DATASIZE (\
    sizeof(uint16_t) \
      + SIZE_SHT45 \
      + SIZE_TSL2591 \
      + SIZE_ILS22QS \
      + SIZE_BMP585 \
      + SIZE_SCD41 \
      + SIZE_SPS30 \
    )
 
 
 
/**
 * @brief Initialization of base sensor data structure
 */
void sensorsBase_Init();
 
/**
 * @brief start timer to off
 * the function is called from PWR_EnterStopMode - timer is started
 */
void sensorsBase_StartTimerToOff();
 
/**
 * @brief stop timer to off
 * the function is called from PWR_ExitStopMode - the timer value is checked and the PWR_ExitStopMode was invoked from this times, system goes to OFF mode setModeDevice(MODEDEVICE_OFF)
 */
void sensorsBase_StopTimerToOff();
 
#endif /* INC_MYSENSORS_BASE_H_ */