NVProperty.h

00001 /*
00002  * This is an unpublished work copyright
00003  * (c) 2019 Helmut Tschemernjak
00004  * 30826 Garbsen (Hannover) Germany
00005  *
00006  *
00007  * Use is granted to registered RadioShuttle licensees only.
00008  * Licensees must own a valid serial number and product code.
00009  * Details see: www.radioshuttle.de
00010  */
00011 
00012 #ifndef __NVPROPERTY_H__
00013 #define __NVPROPERTY_H__
00014 
00015 
00016 #ifndef UNUSED
00017  #define UNUSED(x) (void)(x)
00018 #endif
00019 
00020 class NVProperty {
00021 public:
00022     /*
00023      * The property store size depends on the implementation
00024      * The ESP32 uses the NVS partition therefore the size is being ignored.
00025      * The D21 uses the default 16kByte which is a good tradeoff between
00026      * space needed for the application versus space for properties.
00027      * Larger D21 property space (e.g. 20kB) has the advantage that the
00028      * flash blocks are less busy. For the D21 it is a good idea to
00029      * use increments of 16kB because this is the region locking area size
00030      */
00031 #ifndef TARGET_STM32L0
00032     NVProperty(int propSizekB = 16, bool erase = false);
00033 #else
00034     NVProperty(int propSizekB = 4, bool erase = false);
00035 #endif
00036     ~NVProperty();
00037 public:
00038     enum NVPType {
00039         T_BIT   = 1,
00040         T_8BIT  = 2,
00041         T_16BIT = 3,
00042         T_32BIT = 4,
00043         T_64BIT = 5,
00044         T_STR   = 6,    // strings can be up to 256 bytes including zero
00045         T_BLOB  = 7,    // blobs can be up to 256 bytes long
00046         T_MAX   = 15    // we have only 4 bit space for the NVP types
00047     };
00048     
00049     enum NVPStore {
00050         S_OTP   = 0x01,
00051         S_FLASH = 0x02,
00052         S_RAM   = 0x04,
00053     };
00054     
00055     enum NVPErrCode {
00056         NVP_OK = 0,
00057         NVP_NO_FLASH    = -1,
00058         NVP_NO_RAM      = -2,
00059         NVP_NO_STORE    = -3,
00060         NVP_NO_PERM     = -4,
00061         NVP_ERR_NOSPACE = -5,
00062         NVP_ERR_FAIL    = -6,
00063         NVP_INVALD_PARM = -7,
00064         NVP_ENOENT      = -0x12345687,
00065     };
00066 
00067     /*
00068      * Get property protocol version to allow
00069      * API differences between multiple versions
00070      */
00071     int GetVersion(void) { return 100; };
00072 
00073     /*
00074      * A simple GetProperty retuns its values as an int or int64
00075      * The order should always be S_RAM,S_FLASH, S_OTP
00076      */
00077     int GetProperty(int key, int defaultValue = 0);
00078     int64_t GetProperty64(int key, int64_t defaultValue = 0);
00079     /*
00080      * const char *GetProperty: receives a copy of the propery, use free to release it.
00081      */
00082     const char *GetProperty(int key, const char *defaultValue = NULL);
00083     /*
00084      * when a block gets returned the buffer is filled up to the property
00085      * or max at the bsize length.
00086      * if the buffer is NULL only the size value will be set
00087      */
00088     int GetProperty(int key, void  *buffer, int *size);
00089 
00090     /*
00091      * SetProperty
00092      * It requires to use OpenPropertyStore and finally ClosePropertyStore(true)
00093      * to write out all properties.
00094      * Properties are being limited to 256 bytes. (e.g. 255 long strings or 256 bytes blobs)
00095      *
00096      * Number properties e.g. 0 or 1, or 123 are highly optimized in storage sizes
00097      * therefore the value is automatically being compressed to a bit or a little
00098      * number to use less flash storage space.
00099      */
00100     int SetProperty(int key, NVPType ptype, int64_t value, NVPStore store = S_FLASH);
00101     int SetProperty(int key, NVPType ptype, const char *value, NVPStore store = S_FLASH);
00102     int SetProperty(int key, NVPType ptype, const void *blob, int length, NVPStore store = S_FLASH);
00103     
00104     int EraseProperty(int key, NVPStore store = S_FLASH);
00105     
00106     /*
00107      * ReorgProperties is usually not needed because when a property storage is
00108      * full it reorganizes itself to make space for new properties.
00109      */
00110     int ReorgProperties(NVPStore store = S_FLASH);
00111     /*
00112      * Opens a property store for reading or writing.
00113      */
00114     int OpenPropertyStore(bool forWrite = false);
00115     /*
00116      * Closes the property store and flushes the data, depending on the
00117      * implementation flush may be not needed, e.g. D21
00118      */
00119     int ClosePropertyStore(bool flush = false);
00120 
00121     enum Properties {
00122         RTC_AGING_CAL   = 1, // int8_t the RTC aging calibration value
00123         ADC_VREF        = 2, // the adc refernce volatge in millivolt
00124         HARDWARE_REV    = 3, // the hardware revision of the board
00125         CPUID           = 4, // the internal CPU ID
00126         
00127         LORA_DEVICE_ID  = 10, // uint32_t the LoRa device ID
00128         LORA_CODE_ID    = 11, // uint32_t the Code for the RadioShuttle protocol
00129         LORA_REMOTE_ID  = 12, // specifies the server address
00130         LORA_REMOTE_ID_ALT = 13, // specifies the alternate server address
00131         LORA_RADIO_TYPE = 14,   // 1 = Offline, 3 = Online, 4 = RS_Station_Basic
00132         LORA_FREQUENCY  = 15,   // channel frequency in Hz, e.g. 868100000
00133         LORA_BANDWIDTH  = 16,   // channel bandwidth in Hz, e.g. 125000
00134         LORA_SPREADING_FACTOR = 17, // e.g. 7
00135         LORA_TXPOWER    = 18,   // e.g. 14 for 15 dBm.
00136         LORA_FREQUENCY_OFFSET = 19,
00137         LORA_APP_PWD    = 20,   // passwords are per app, there are only two placeholders
00138         LORA_APP_PWD_ALT = 21,
00139 
00140         LOC_LONGITUDE   = 25,   // a string
00141         LOC_LATITUDE    = 26,   // a string
00142         LOC_NAME        = 27,   // a string with the location name
00143         HOSTNAME        = 28,   // the device host name
00144         
00145         WIFI_SSID       = 30,
00146         WIFI_PASSWORD   = 31,
00147         WIFI_SSID_ALT   = 32,
00148         WIFI_PASSWORD_ALT = 33,
00149         USE_DHCP        = 34,
00150         MAC_ADDR        = 35,
00151         NET_IP_ADDR     = 36,
00152         NET_IP_ROUTER   = 37,
00153         NET_IP_DNS_SERVER = 38,
00154         NET_IP_DNS_SERVER_ALT = 39,
00155         
00156         MQTT_SERVER     = 40,   // url mqtt or mqtts://user.password@server:port
00157         MQTT_SERVER_ALT = 41,
00158         MQTT_TOPIC_INFO = 42,
00159         MQTT_TOPIC_ALARM= 43,
00160         MQTT_TOPIC_CONTROL = 44,
00161         MQTT_TOPIC_4    = 45,
00162         MQTT_TOPIC_5    = 46,
00163         
00164         NET_NTP_SERVER  = 50,
00165         NET_NTP_SERVER_ALT = 51,
00166         NET_NTP_GMTOFFSET = 52,
00167         NET_NTP_DAYLIGHTOFFSET = 53,
00168 
00169         ALARM_STATUS    = 60,   // alarm on=0, off !0
00170         
00171         PRIVATE_RANGE_START = 128,
00172         PRIVATE_RANGE_END   = 254,
00173         MAX_PROPERTIES      = 254, // 1-254
00174     };
00175 
00176 private:
00177     NVPropertyProviderInterface *_ram;
00178     NVPropertyProviderInterface *_flash;
00179     NVPropertyProviderInterface *_otp;
00180     bool _allowWrite;
00181     bool _didOpen;
00182 };
00183 
00184 #endif