Helmut Tschemernjak / NVProperty

NVProperty generic key value store using the MCU flash area.

Dependents:   Turtle_RadioShuttle

NVProperty.h@1:3a8297ad8cd9, 2019-01-24 (annotated)

Committer:
Helmut Tschemernjak
Date:
Thu Jan 24 14:28:11 2019 +0100
Revision:
1:3a8297ad8cd9
Child:
12:5539cdc8be4b
Added new files

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Helmut Tschemernjak 1:3a8297ad8cd9 1 /*
Helmut Tschemernjak 1:3a8297ad8cd9 2 * This is an unpublished work copyright
Helmut Tschemernjak 1:3a8297ad8cd9 3 * (c) 2019 Helmut Tschemernjak
Helmut Tschemernjak 1:3a8297ad8cd9 4 * 30826 Garbsen (Hannover) Germany
Helmut Tschemernjak 1:3a8297ad8cd9 5 *
Helmut Tschemernjak 1:3a8297ad8cd9 6 *
Helmut Tschemernjak 1:3a8297ad8cd9 7 * Use is granted to registered RadioShuttle licensees only.
Helmut Tschemernjak 1:3a8297ad8cd9 8 * Licensees must own a valid serial number and product code.
Helmut Tschemernjak 1:3a8297ad8cd9 9 * Details see: www.radioshuttle.de
Helmut Tschemernjak 1:3a8297ad8cd9 10 */
Helmut Tschemernjak 1:3a8297ad8cd9 11
Helmut Tschemernjak 1:3a8297ad8cd9 12 #ifndef __NVPROPERTY_H__
Helmut Tschemernjak 1:3a8297ad8cd9 13 #define __NVPROPERTY_H__
Helmut Tschemernjak 1:3a8297ad8cd9 14
Helmut Tschemernjak 1:3a8297ad8cd9 15
Helmut Tschemernjak 1:3a8297ad8cd9 16 #ifndef UNUSED
Helmut Tschemernjak 1:3a8297ad8cd9 17 #define UNUSED(x) (void)(x)
Helmut Tschemernjak 1:3a8297ad8cd9 18 #endif
Helmut Tschemernjak 1:3a8297ad8cd9 19
Helmut Tschemernjak 1:3a8297ad8cd9 20 class NVProperty {
Helmut Tschemernjak 1:3a8297ad8cd9 21 public:
Helmut Tschemernjak 1:3a8297ad8cd9 22 /*
Helmut Tschemernjak 1:3a8297ad8cd9 23 * The property store size depends on the implementation
Helmut Tschemernjak 1:3a8297ad8cd9 24 * The ESP32 uses the NVS partition therefore the size is being ignored.
Helmut Tschemernjak 1:3a8297ad8cd9 25 * The D21 uses the default 16kByte which is a good tradeoff between
Helmut Tschemernjak 1:3a8297ad8cd9 26 * space needed for the application versus space for properties.
Helmut Tschemernjak 1:3a8297ad8cd9 27 * Larger D21 property space (e.g. 20kB) has the advantage that the
Helmut Tschemernjak 1:3a8297ad8cd9 28 * flash blocks are less busy. For the D21 it is a good idea to
Helmut Tschemernjak 1:3a8297ad8cd9 29 * use increments of 16kB because this is the region locking area size
Helmut Tschemernjak 1:3a8297ad8cd9 30 */
Helmut Tschemernjak 1:3a8297ad8cd9 31 NVProperty(int propSizekB = 16, bool erase = false);
Helmut Tschemernjak 1:3a8297ad8cd9 32 ~NVProperty();
Helmut Tschemernjak 1:3a8297ad8cd9 33 public:
Helmut Tschemernjak 1:3a8297ad8cd9 34 enum NVPType {
Helmut Tschemernjak 1:3a8297ad8cd9 35 T_BIT = 1,
Helmut Tschemernjak 1:3a8297ad8cd9 36 T_8BIT = 2,
Helmut Tschemernjak 1:3a8297ad8cd9 37 T_16BIT = 3,
Helmut Tschemernjak 1:3a8297ad8cd9 38 T_32BIT = 4,
Helmut Tschemernjak 1:3a8297ad8cd9 39 T_64BIT = 5,
Helmut Tschemernjak 1:3a8297ad8cd9 40 T_STR = 6, // strings can be up to 256 bytes including zero
Helmut Tschemernjak 1:3a8297ad8cd9 41 T_BLOB = 7, // blobs can be up to 256 bytes long
Helmut Tschemernjak 1:3a8297ad8cd9 42 T_MAX = 15 // we have only 4 bit space for the NVP types
Helmut Tschemernjak 1:3a8297ad8cd9 43 };
Helmut Tschemernjak 1:3a8297ad8cd9 44
Helmut Tschemernjak 1:3a8297ad8cd9 45 enum NVPStore {
Helmut Tschemernjak 1:3a8297ad8cd9 46 S_OTP = 0x01,
Helmut Tschemernjak 1:3a8297ad8cd9 47 S_FLASH = 0x02,
Helmut Tschemernjak 1:3a8297ad8cd9 48 S_RAM = 0x04,
Helmut Tschemernjak 1:3a8297ad8cd9 49 };
Helmut Tschemernjak 1:3a8297ad8cd9 50
Helmut Tschemernjak 1:3a8297ad8cd9 51 enum NVPErrCode {
Helmut Tschemernjak 1:3a8297ad8cd9 52 NVP_OK = 0,
Helmut Tschemernjak 1:3a8297ad8cd9 53 NVP_NO_FLASH = -1,
Helmut Tschemernjak 1:3a8297ad8cd9 54 NVP_NO_RAM = -2,
Helmut Tschemernjak 1:3a8297ad8cd9 55 NVP_NO_STORE = -3,
Helmut Tschemernjak 1:3a8297ad8cd9 56 NVP_NO_PERM = -4,
Helmut Tschemernjak 1:3a8297ad8cd9 57 NVP_ERR_NOSPACE = -5,
Helmut Tschemernjak 1:3a8297ad8cd9 58 NVP_ERR_FAIL = -6,
Helmut Tschemernjak 1:3a8297ad8cd9 59 NVP_INVALD_PARM = -7,
Helmut Tschemernjak 1:3a8297ad8cd9 60 NVP_ENOENT = -0x12345687,
Helmut Tschemernjak 1:3a8297ad8cd9 61 };
Helmut Tschemernjak 1:3a8297ad8cd9 62
Helmut Tschemernjak 1:3a8297ad8cd9 63 /*
Helmut Tschemernjak 1:3a8297ad8cd9 64 * Get property protocol version to allow
Helmut Tschemernjak 1:3a8297ad8cd9 65 * API differences between multiple versions
Helmut Tschemernjak 1:3a8297ad8cd9 66 */
Helmut Tschemernjak 1:3a8297ad8cd9 67 int GetVersion(void) { return 100; };
Helmut Tschemernjak 1:3a8297ad8cd9 68
Helmut Tschemernjak 1:3a8297ad8cd9 69 /*
Helmut Tschemernjak 1:3a8297ad8cd9 70 * A simple GetProperty retuns its values as an int or int64
Helmut Tschemernjak 1:3a8297ad8cd9 71 * The order should always be S_RAM,S_FLASH, S_OTP
Helmut Tschemernjak 1:3a8297ad8cd9 72 */
Helmut Tschemernjak 1:3a8297ad8cd9 73 int GetProperty(int key, int defaultValue = 0);
Helmut Tschemernjak 1:3a8297ad8cd9 74 int64_t GetProperty64(int key, int64_t defaultValue = 0);
Helmut Tschemernjak 1:3a8297ad8cd9 75 /*
Helmut Tschemernjak 1:3a8297ad8cd9 76 * const char *GetProperty: receives a copy of the propery, use free to release it.
Helmut Tschemernjak 1:3a8297ad8cd9 77 */
Helmut Tschemernjak 1:3a8297ad8cd9 78 const char *GetProperty(int key, const char *defaultValue = NULL);
Helmut Tschemernjak 1:3a8297ad8cd9 79 /*
Helmut Tschemernjak 1:3a8297ad8cd9 80 * when a block gets returned the buffer is filled up to the property
Helmut Tschemernjak 1:3a8297ad8cd9 81 * or max at the bsize length.
Helmut Tschemernjak 1:3a8297ad8cd9 82 * if the buffer is NULL only the size value will be set
Helmut Tschemernjak 1:3a8297ad8cd9 83 */
Helmut Tschemernjak 1:3a8297ad8cd9 84 int GetProperty(int key, void *buffer, int *size);
Helmut Tschemernjak 1:3a8297ad8cd9 85
Helmut Tschemernjak 1:3a8297ad8cd9 86 /*
Helmut Tschemernjak 1:3a8297ad8cd9 87 * SetProperty
Helmut Tschemernjak 1:3a8297ad8cd9 88 * It requires to use OpenPropertyStore and finally ClosePropertyStore(true)
Helmut Tschemernjak 1:3a8297ad8cd9 89 * to write out all properties.
Helmut Tschemernjak 1:3a8297ad8cd9 90 * Properties are being limited to 256 bytes. (e.g. 255 long strings or 256 bytes blobs)
Helmut Tschemernjak 1:3a8297ad8cd9 91 *
Helmut Tschemernjak 1:3a8297ad8cd9 92 * Number properties e.g. 0 or 1, or 123 are highly optimized in storage sizes
Helmut Tschemernjak 1:3a8297ad8cd9 93 * therefore the value is automatically being compressed to a bit or a little
Helmut Tschemernjak 1:3a8297ad8cd9 94 * number to use less flash storage space.
Helmut Tschemernjak 1:3a8297ad8cd9 95 */
Helmut Tschemernjak 1:3a8297ad8cd9 96 int SetProperty(int key, NVPType ptype, int64_t value, NVPStore store = S_FLASH);
Helmut Tschemernjak 1:3a8297ad8cd9 97 int SetProperty(int key, NVPType ptype, const char *value, NVPStore store = S_FLASH);
Helmut Tschemernjak 1:3a8297ad8cd9 98 int SetProperty(int key, NVPType ptype, const void *blob, int length, NVPStore store = S_FLASH);
Helmut Tschemernjak 1:3a8297ad8cd9 99
Helmut Tschemernjak 1:3a8297ad8cd9 100 int EraseProperty(int key, NVPStore store = S_FLASH);
Helmut Tschemernjak 1:3a8297ad8cd9 101
Helmut Tschemernjak 1:3a8297ad8cd9 102 /*
Helmut Tschemernjak 1:3a8297ad8cd9 103 * ReorgProperties is usually not needed because when a property storage is
Helmut Tschemernjak 1:3a8297ad8cd9 104 * full it reorganizes itself to make space for new properties.
Helmut Tschemernjak 1:3a8297ad8cd9 105 */
Helmut Tschemernjak 1:3a8297ad8cd9 106 int ReorgProperties(NVPStore store = S_FLASH);
Helmut Tschemernjak 1:3a8297ad8cd9 107 /*
Helmut Tschemernjak 1:3a8297ad8cd9 108 * Opens a property store for reading or writing.
Helmut Tschemernjak 1:3a8297ad8cd9 109 */
Helmut Tschemernjak 1:3a8297ad8cd9 110 int OpenPropertyStore(bool forWrite = false);
Helmut Tschemernjak 1:3a8297ad8cd9 111 /*
Helmut Tschemernjak 1:3a8297ad8cd9 112 * Closes the property store and flushes the data, depending on the
Helmut Tschemernjak 1:3a8297ad8cd9 113 * implementation flush may be not needed, e.g. D21
Helmut Tschemernjak 1:3a8297ad8cd9 114 */
Helmut Tschemernjak 1:3a8297ad8cd9 115 int ClosePropertyStore(bool flush = false);
Helmut Tschemernjak 1:3a8297ad8cd9 116
Helmut Tschemernjak 1:3a8297ad8cd9 117 enum Properties {
Helmut Tschemernjak 1:3a8297ad8cd9 118 RTC_AGING_CAL = 1, // int8_t the RTC aging calibration value
Helmut Tschemernjak 1:3a8297ad8cd9 119 ADC_VREF = 2, // the adc refernce volatge in millivolt
Helmut Tschemernjak 1:3a8297ad8cd9 120 HARDWARE_REV = 3, // the hardware revision of the board
Helmut Tschemernjak 1:3a8297ad8cd9 121 CPUID = 4, // the internal CPU ID
Helmut Tschemernjak 1:3a8297ad8cd9 122
Helmut Tschemernjak 1:3a8297ad8cd9 123 LORA_DEVICE_ID = 10, // uint32_t the LoRa device ID
Helmut Tschemernjak 1:3a8297ad8cd9 124 LORA_CODE_ID = 11, // uint32_t the Code for the RadioShuttle protocol
Helmut Tschemernjak 1:3a8297ad8cd9 125 LORA_REMOTE_ID = 12, // specifies the server address
Helmut Tschemernjak 1:3a8297ad8cd9 126 LORA_REMOTE_ID_ALT = 13, // specifies the alternate server address
Helmut Tschemernjak 1:3a8297ad8cd9 127 LORA_RADIO_TYPE = 14, // 1 = Offline, 3 = Online, 4 = RS_Station_Basic
Helmut Tschemernjak 1:3a8297ad8cd9 128 LORA_FREQUENCY = 15, // channel frequency in Hz, e.g. 868100000
Helmut Tschemernjak 1:3a8297ad8cd9 129 LORA_BANDWIDTH = 16, // channel bandwidth in Hz, e.g. 125000
Helmut Tschemernjak 1:3a8297ad8cd9 130 LORA_SPREADING_FACTOR = 17, // e.g. 7
Helmut Tschemernjak 1:3a8297ad8cd9 131 LORA_TXPOWER = 18, // e.g. 14 for 15 dBm.
Helmut Tschemernjak 1:3a8297ad8cd9 132 LORA_FREQUENCY_OFFSET = 19,
Helmut Tschemernjak 1:3a8297ad8cd9 133 LORA_APP_PWD = 20, // passwords are per app, there are only two placeholders
Helmut Tschemernjak 1:3a8297ad8cd9 134 LORA_APP_PWD_ALT = 21,
Helmut Tschemernjak 1:3a8297ad8cd9 135
Helmut Tschemernjak 1:3a8297ad8cd9 136 LOC_LONGITUDE = 25, // a string
Helmut Tschemernjak 1:3a8297ad8cd9 137 LOC_LATITUDE = 26, // a string
Helmut Tschemernjak 1:3a8297ad8cd9 138 LOC_NAME = 27, // a string with the location name
Helmut Tschemernjak 1:3a8297ad8cd9 139 HOSTNAME = 28, // the device host name
Helmut Tschemernjak 1:3a8297ad8cd9 140
Helmut Tschemernjak 1:3a8297ad8cd9 141 WIFI_SSID = 30,
Helmut Tschemernjak 1:3a8297ad8cd9 142 WIFI_PASSWORD = 31,
Helmut Tschemernjak 1:3a8297ad8cd9 143 WIFI_SSID_ALT = 32,
Helmut Tschemernjak 1:3a8297ad8cd9 144 WIFI_PASSWORD_ALT = 33,
Helmut Tschemernjak 1:3a8297ad8cd9 145 USE_DHCP = 34,
Helmut Tschemernjak 1:3a8297ad8cd9 146 MAC_ADDR = 35,
Helmut Tschemernjak 1:3a8297ad8cd9 147 NET_IP_ADDR = 36,
Helmut Tschemernjak 1:3a8297ad8cd9 148 NET_IP_ROUTER = 37,
Helmut Tschemernjak 1:3a8297ad8cd9 149 NET_IP_DNS_SERVER = 38,
Helmut Tschemernjak 1:3a8297ad8cd9 150
Helmut Tschemernjak 1:3a8297ad8cd9 151 MQTT_SERVER = 40, // url mqtt or mqtts://user.password@server:port
Helmut Tschemernjak 1:3a8297ad8cd9 152 MQTT_SERVER_ALT = 41,
Helmut Tschemernjak 1:3a8297ad8cd9 153 MQTT_TOPIC_INFO = 42,
Helmut Tschemernjak 1:3a8297ad8cd9 154 MQTT_TOPIC_ALARM= 43,
Helmut Tschemernjak 1:3a8297ad8cd9 155 MQTT_TOPIC_CONTROL = 44,
Helmut Tschemernjak 1:3a8297ad8cd9 156 MQTT_TOPIC_4 = 45,
Helmut Tschemernjak 1:3a8297ad8cd9 157 MQTT_TOPIC_5 = 46,
Helmut Tschemernjak 1:3a8297ad8cd9 158
Helmut Tschemernjak 1:3a8297ad8cd9 159 ALARM_STATUS = 50, // alarm on=0, off !0
Helmut Tschemernjak 1:3a8297ad8cd9 160
Helmut Tschemernjak 1:3a8297ad8cd9 161 PRIVATE_RANGE_START = 128,
Helmut Tschemernjak 1:3a8297ad8cd9 162 PRIVATE_RANGE_END = 254,
Helmut Tschemernjak 1:3a8297ad8cd9 163 PROPERTIES_EOF = 255,
Helmut Tschemernjak 1:3a8297ad8cd9 164 MAX_PROPERTIES = 256,
Helmut Tschemernjak 1:3a8297ad8cd9 165 };
Helmut Tschemernjak 1:3a8297ad8cd9 166
Helmut Tschemernjak 1:3a8297ad8cd9 167 private:
Helmut Tschemernjak 1:3a8297ad8cd9 168 NVPropertyProviderInterface *_ram;
Helmut Tschemernjak 1:3a8297ad8cd9 169 NVPropertyProviderInterface *_flash;
Helmut Tschemernjak 1:3a8297ad8cd9 170 NVPropertyProviderInterface *_otp;
Helmut Tschemernjak 1:3a8297ad8cd9 171 bool _allowWrite;
Helmut Tschemernjak 1:3a8297ad8cd9 172 bool _didOpen;
Helmut Tschemernjak 1:3a8297ad8cd9 173 };
Helmut Tschemernjak 1:3a8297ad8cd9 174
Helmut Tschemernjak 1:3a8297ad8cd9 175 #endif