AllWize Library
AllWize.h
Go to the documentation of this file.
1 /*
2 
3 AllWize Library
4 
5 Copyright (C) 2018-2020 by AllWize <github@allwize.io>
6 
7 This program is free software: you can redistribute it and/or modify
8 it under the terms of the GNU General Public License as published by
9 the Free Software Foundation, either version 3 of the License, or
10 (at your option) any later version.
11 
12 This program is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 GNU Lesser General Public License for more details.
16 
17 You should have received a copy of the GNU Lesser General Public License
18 along with this program. If not, see <http://www.gnu.org/licenses/>.
19 
20 */
21 
27 #ifndef ALLWIZE_H
28 #define ALLWIZE_H
29 
30 #include <Arduino.h>
31 #include "RC1701HP.h"
32 #include "OMS.h"
33 #include <Stream.h>
34 #if not defined(ARDUINO_ARCH_SAMD) && not defined(ARDUINO_ARCH_ESP32)
35 #include <SoftwareSerial.h>
36 #endif
37 
38 // -----------------------------------------------------------------------------
39 // Types & definitions
40 // -----------------------------------------------------------------------------
41 
42 // General
43 #define MODEM_DEFAULT_BAUDRATE BAUDRATE_19200
44 #define GPIO_NONE 0x99
45 #define RX_BUFFER_SIZE 255
46 #define DEFAULT_TIMEOUT 100
47 #define HARDWARE_SERIAL_PORT 1
48 #define DEFAULT_MBUS_MODE MBUS_MODE_N1
49 
50 #ifndef USE_MEMORY_CACHE
51 #define USE_MEMORY_CACHE 1
52 #endif
53 
54 typedef struct {
55  uint8_t c;
56  uint8_t ci;
57  char man[4];
58  uint8_t type;
59  uint8_t version;
60  uint8_t address[4];
61  uint8_t len;
62  uint8_t data[RX_BUFFER_SIZE];
63  uint8_t rssi;
64  uint8_t wize_control;
65  uint8_t wize_network_id;
66  uint16_t wize_counter;
69 
70 // -----------------------------------------------------------------------------
71 // DEBUG
72 // -----------------------------------------------------------------------------
73 
74 // Uncomment this to the proper port
75 // or define it in your build settings if you want
76 // to get low level debug information via serial
77 //#define ALLWIZE_DEBUG_PORT Serial
78 
79 #if defined(ALLWIZE_DEBUG_PORT)
80  #define ALLWIZE_DEBUG_PRINT(...) ALLWIZE_DEBUG_PORT.print(__VA_ARGS__)
81  #define ALLWIZE_DEBUG_PRINTLN(...) ALLWIZE_DEBUG_PORT.println(__VA_ARGS__)
82 #else
83  #define ALLWIZE_DEBUG_PRINT(...)
84  #define ALLWIZE_DEBUG_PRINTLN(...)
85 #endif
86 
87 // -----------------------------------------------------------------------------
88 // Class prototype
89 // -----------------------------------------------------------------------------
90 
91 class AllWize {
92 
93  public:
94 
95  AllWize(HardwareSerial * serial, uint8_t reset_gpio = GPIO_NONE, uint8_t config_gpio = GPIO_NONE);
96  #if not defined(ARDUINO_ARCH_SAMD) && not defined(ARDUINO_ARCH_ESP32)
97  AllWize(SoftwareSerial * serial, uint8_t reset_gpio = GPIO_NONE, uint8_t config_gpio = GPIO_NONE);
98  #endif
99  AllWize(uint8_t rx, uint8_t tx, uint8_t reset_gpio = GPIO_NONE, uint8_t config_gpio = GPIO_NONE);
100 
101  void begin(uint8_t baudrate = MODEM_DEFAULT_BAUDRATE);
102  bool reset();
103  void softReset();
104  bool factoryReset();
105  void sleep();
106  void wakeup();
107  bool ready();
108  bool waitForReady(uint32_t timeout = DEFAULT_TIMEOUT);
109  void dump(Stream & debug);
110 
111  bool ack();
112  bool send(uint8_t * buffer, uint8_t len);
113  bool send(const char * buffer);
114  bool available();
115  bool enableRX(bool enable);
117 
118  void setControlInformation(uint8_t ci);
119  uint8_t getControlInformation();
120 
121  void master();
122  void slave();
123  void repeater();
124 
125  void setChannel(uint8_t channel, bool persist = false);
126  void setPower(uint8_t power, bool persist = false);
127  void setDataRate(uint8_t dr);
128  void setMode(uint8_t mode, bool persist = false);
129  void setSleepMode(uint8_t mode);
130  void setAppendRSSI(bool value);
131  void setPreamble(uint8_t preamble);
132  void setTimeout(uint16_t ms);
133  void setNetworkRole(uint8_t role);
134  void setLEDControl(uint8_t value);
135  void setDataInterface(uint8_t value);
136  void setControlField(uint8_t value, bool persist = false);
137  void setInstallMode(uint8_t mode, bool persist = false);
138  void setEncryptFlag(uint8_t flag);
139  void setDecryptFlag(uint8_t flag);
140  void setKey(uint8_t reg, const uint8_t * key);
141  void setDefaultKey(const uint8_t * key);
142  void setAccessNumber(uint8_t value);
143  void setBaudRate(uint8_t baudrate);
144 
145  uint8_t getChannel();
146  uint8_t getPower();
147  uint8_t getDataRate();
148  uint8_t getMode();
149  uint8_t getSleepMode();
150  uint8_t getPreamble();
151  uint8_t getDataInterface();
152  uint8_t getControlField();
153  bool getAppendRSSI();
154  uint16_t getTimeout();
155  uint8_t getNetworkRole();
156  uint8_t getLEDControl();
157  uint8_t getInstallMode();
158  uint8_t getEncryptFlag();
159  uint8_t getDecryptFlag();
160  void getDefaultKey(uint8_t * key);
161  uint8_t getBaudRate();
162  uint32_t getBaudRateSpeed(uint8_t value);
163 
164  float getRSSI();
165  uint8_t getTemperature();
166  uint16_t getVoltage();
167  String getMID();
168  bool setMID(uint16_t mid);
169  String getUID();
170  bool setUID(uint32_t uid);
171  uint8_t getVersion();
172  void setVersion(uint8_t version);
173  uint8_t getDevice();
174  void setDevice(uint8_t type);
175  String getPartNumber();
177  String getFirmwareVersion();
178  String getSerialNumber();
179  double getFrequency(uint8_t channel);
180  uint16_t getDataRateSpeed(uint8_t dr);
181  uint8_t getModuleType();
182  String getModuleTypeName();
183 
184  // Wize specific
185  bool setWizeControl(uint8_t wize_control);
186  void setWizeOperatorId(uint16_t wize_network_id);
187  void setWizeNetworkId(uint16_t wize_network_id);
188  void setWizeApplication(uint8_t wize_application);
189  void setCounter(uint16_t counter);
190  uint16_t getCounter();
191 
192  protected:
193 
194  void _init();
195 
196  uint8_t _getAddress(uint8_t slot);
197  bool _setConfig(bool value);
198  int8_t _sendCommand(uint8_t command, uint8_t * data, uint8_t len);
199  int8_t _sendCommand(uint8_t command, uint8_t data);
200  int8_t _sendCommand(uint8_t command);
201 
202  bool _cacheMemory(uint8_t * buffer);
203  uint8_t _getMemory(uint8_t address);
204  uint8_t _getMemory(uint8_t address, uint8_t *buffer, uint8_t len);
205  bool _setMemory(uint8_t address, uint8_t data);
206  bool _setMemory(uint8_t address, uint8_t * data, uint8_t len);
207 
208  bool _setSlot(uint8_t slot, uint8_t data);
209  bool _setSlot(uint8_t slot, uint8_t * data, uint8_t len);
210  uint8_t _getSlot(uint8_t slot);
211  uint8_t _getSlot(uint8_t slot, uint8_t * buffer, uint8_t len);
212  String _getSlotAsHexString(uint8_t slot, uint8_t len);
213  String _getSlotAsString(uint8_t slot, uint8_t len);
214 
215  void _readModel();
216  bool _decode();
217 
218  void _flush();
219  void _resetSerial();
220  uint8_t _send(uint8_t * buffer, uint8_t len);
221  uint8_t _send(uint8_t ch);
222  int8_t _receive();
223  int8_t _sendAndReceive(uint8_t * buffer, uint8_t len);
224  int8_t _sendAndReceive(uint8_t ch);
225 
226  int _timedRead();
227  int _readBytes(char * buffer, uint16_t len);
228  int _readBytesUntil(char terminator, char * buffer, uint16_t len);
229  void _hex2bin(char * hex, uint8_t * bin, uint8_t len);
230  void _bin2hex(uint8_t * bin, char * hex, uint8_t len);
231 
232  void _niceDelay(uint32_t ms);
233 
234  private:
235 
236  // -------------------------------------------------------------------------
237 
238  protected:
239 
240  int8_t _rx = -1;
241  int8_t _tx = -1;
242 
243  Stream * _stream = NULL;
244  HardwareSerial * _hw_serial = NULL;
245  #if defined(ARDUINO_ARCH_SAMD)
246  // Uart * _sw_serial = NULL;
247  #elif defined(ARDUINO_ARCH_ESP32)
248  // Nothing
249  #else
250  SoftwareSerial * _sw_serial = NULL;
251  #endif
252 
255  bool _config = false;
257  uint32_t _baudrate = 19200;
258 
260  uint8_t _mbus_mode = 0xFF;
261  uint8_t _data_interface = 0xFF;
262  bool _append_rssi = false;
263  uint8_t _access_number = 0;
265 
266  // Memory buffer
267  #if USE_MEMORY_CACHE
268  bool _ready = false;
269  uint8_t _memory[0x100] = {0xFF};
270  #endif
271 
272  String _model;
273  String _hw;
274  String _fw;
275 
276  // Wize specific
277  uint8_t _wize_control = 0x00;
278  uint16_t _wize_network_id = 0;
279  uint8_t _wize_application = 0xFE;
280  uint16_t _counter = 0;
281 
282  // Message buffers
285  uint8_t _pointer = 0;
286 
287 };
288 
289 #endif // ALLWIZE_H
uint8_t _data_interface
Definition: AllWize.h:261
String getModuleTypeName()
Returns the module type.
Definition: AllWize.cpp:1120
uint8_t _access_number
Definition: AllWize.h:263
uint8_t getChannel()
Gets the channel stored in non-volatile memory.
Definition: AllWize.cpp:598
#define MODEM_DEFAULT_BAUDRATE
Definition: AllWize.h:43
void setInstallMode(uint8_t mode, bool persist=false)
Sets the module in one of the available operations modes.
Definition: AllWize.cpp:839
uint8_t rssi
Definition: AllWize.h:63
bool enableRX(bool enable)
Enables or disables RF recever.
Definition: AllWize.cpp:442
uint8_t version
Definition: AllWize.h:59
String _model
Definition: AllWize.h:272
bool setUID(uint32_t uid)
Saved the UID into the module memory.
Definition: AllWize.cpp:1035
bool ack()
Sends an ACK.
Definition: AllWize.cpp:431
void setEncryptFlag(uint8_t flag)
Sets the encrypt flag setting.
Definition: AllWize.cpp:860
uint8_t getSleepMode()
Gets the sleep mode stored in non-volatile memory.
Definition: AllWize.cpp:700
uint8_t getLEDControl()
Gets the current LED control.
Definition: AllWize.cpp:791
uint8_t getPower()
Gets the RF power stored in non-volatile memory.
Definition: AllWize.cpp:620
uint8_t len
Definition: AllWize.h:61
String _fw
Definition: AllWize.h:274
int _readBytes(char *buffer, uint16_t len)
Reads the stream buffer up to a number of bytes.
Definition: AllWize.cpp:1800
void setWizeApplication(uint8_t wize_application)
Sets the wize applicaton field in the transpoprt layer.
Definition: AllWize.cpp:538
uint8_t getEncryptFlag()
Gets the encrypt flag setting.
Definition: AllWize.cpp:870
void setVersion(uint8_t version)
Sets the device version.
Definition: AllWize.cpp:1056
void slave()
Sets the module in slave mode.
Definition: AllWize.cpp:249
allwize_message_t _message
Definition: AllWize.h:283
void setPower(uint8_t power, bool persist=false)
Sets the RF power.
Definition: AllWize.cpp:607
void setNetworkRole(uint8_t role)
Sets the network role.
Definition: AllWize.cpp:766
uint8_t _wize_application
Definition: AllWize.h:279
uint32_t getBaudRateSpeed(uint8_t value)
Gets the UART baud rate speed in bps.
Definition: AllWize.cpp:951
bool getAppendRSSI()
Gets the current RSSI mode value.
Definition: AllWize.cpp:721
bool _decode()
Decodes the current RX buffer contents.
Definition: AllWize.cpp:1549
uint8_t getVersion()
Returns the device version from non-volatile memory.
Definition: AllWize.cpp:1048
uint16_t _wize_network_id
Definition: AllWize.h:278
void setControlField(uint8_t value, bool persist=false)
Sets the control field value.
Definition: AllWize.cpp:819
void begin(uint8_t baudrate=MODEM_DEFAULT_BAUDRATE)
Inits the module communications.
Definition: AllWize.cpp:91
int8_t _sendCommand(uint8_t command, uint8_t *data, uint8_t len)
Sends a command with the given data.
Definition: AllWize.cpp:1207
void setMode(uint8_t mode, bool persist=false)
Sets the module in one of the available MBus modes.
Definition: AllWize.cpp:662
void _resetSerial()
Resets the serial object.
Definition: AllWize.cpp:120
void dump(Stream &debug)
Dumps the current memory configuration to the given stream.
Definition: AllWize.cpp:307
String getRequiredHardwareVersion()
Returns the minimum required hardware version to run the current firmware.
Definition: AllWize.cpp:1088
void setPreamble(uint8_t preamble)
Sets the preamble length frame format.
Definition: AllWize.cpp:729
uint8_t getControlField()
Gets the control field value stored in non-volatile memory.
Definition: AllWize.cpp:830
uint16_t _counter
Definition: AllWize.h:280
uint8_t getPreamble()
Gets the preamble length frame format.
Definition: AllWize.cpp:739
int8_t _receive()
Listens to incoming data from the module until timeout or END_OF_RESPONSE.
Definition: AllWize.cpp:1732
bool send(uint8_t *buffer, uint8_t len)
Sends a byte array.
Definition: AllWize.cpp:366
void setCounter(uint16_t counter)
Sets the wize couonter field in the transpoprt layer.
Definition: AllWize.cpp:546
uint8_t wize_network_id
Definition: AllWize.h:65
void softReset()
Cleans the RX/TX line.
Definition: AllWize.cpp:197
bool _ready
Definition: AllWize.h:268
uint8_t _getSlot(uint8_t slot)
Returns the contents of single-byte memory slot.
Definition: AllWize.cpp:1480
uint8_t _buffer[RX_BUFFER_SIZE]
Definition: AllWize.h:284
String getUID()
Returns the Unique ID string.
Definition: AllWize.cpp:1027
uint16_t wize_counter
Definition: AllWize.h:66
uint8_t getTemperature()
Returns the internal temperature of the module.
Definition: AllWize.cpp:975
void setWizeOperatorId(uint16_t wize_network_id)
Use AllWize::setWizeNetworkId instead.
Definition: AllWize.cpp:522
bool ready()
Test whether the radio module is ready or not.
Definition: AllWize.cpp:285
void setSleepMode(uint8_t mode)
Sets the sleep mode.
Definition: AllWize.cpp:692
uint8_t getDecryptFlag()
Gets the decrypt flag setting.
Definition: AllWize.cpp:886
void setControlInformation(uint8_t ci)
Sets the control information byte.
Definition: AllWize.cpp:566
void wakeup()
Wakes up the radio from sleep mode.
Definition: AllWize.cpp:276
void master()
Sets the module in master mode.
Definition: AllWize.cpp:234
bool available()
Returns true if a new message has been received and decoded This method has to be called in the main ...
Definition: AllWize.cpp:457
String _getSlotAsHexString(uint8_t slot, uint8_t len)
Returns the contents of the memory from a certain address as an HEX String.
Definition: AllWize.cpp:1493
uint8_t getDevice()
Returns the device type from non-volatile memory.
Definition: AllWize.cpp:1064
void setLEDControl(uint8_t value)
Sets the LED control.
Definition: AllWize.cpp:782
int8_t _sendAndReceive(uint8_t *buffer, uint8_t len)
Sends a binary buffer and waits for response. Returns the number of bytes received and stored in the ...
Definition: AllWize.cpp:1743
uint8_t _pointer
Definition: AllWize.h:285
void setDecryptFlag(uint8_t flag)
Sets the decrypt flag setting.
Definition: AllWize.cpp:878
uint32_t _baudrate
Definition: AllWize.h:257
#define DEFAULT_TIMEOUT
Definition: AllWize.h:46
String getPartNumber()
Returns the module part number.
Definition: AllWize.cpp:1080
uint8_t _wize_control
Definition: AllWize.h:277
uint8_t ci
Definition: AllWize.h:56
uint8_t getModuleType()
Returns the module type.
Definition: AllWize.cpp:1112
#define GPIO_NONE
Definition: AllWize.h:44
void repeater()
Sets the module in repeater mode.
Definition: AllWize.cpp:260
bool waitForReady(uint32_t timeout=DEFAULT_TIMEOUT)
Waits for timeout millis for the module to be ready.
Definition: AllWize.cpp:294
void setTimeout(uint16_t ms)
Sets the buffer timeout (also used for auto sleep modes)
Definition: AllWize.cpp:747
uint8_t getNetworkRole()
Gets the current network role.
Definition: AllWize.cpp:774
bool setWizeControl(uint8_t wize_control)
Sets the wize control field in the transpoprt layer.
Definition: AllWize.cpp:512
uint8_t wize_control
Definition: AllWize.h:64
bool _config
Definition: AllWize.h:255
int8_t _tx
Definition: AllWize.h:241
String _getSlotAsString(uint8_t slot, uint8_t len)
Returns the contents of the memory from a certain address as a String object.
Definition: AllWize.cpp:1510
int8_t _rx
Definition: AllWize.h:240
uint32_t _timeout
Definition: AllWize.h:256
uint16_t getCounter()
Gets the current wize counter.
Definition: AllWize.cpp:554
AllWize(HardwareSerial *serial, uint8_t reset_gpio=GPIO_NONE, uint8_t config_gpio=GPIO_NONE)
AllWize object constructor.
Definition: AllWize.cpp:40
int _readBytesUntil(char terminator, char *buffer, uint16_t len)
Reads the stream buffer up to a certain char or times out.
Definition: AllWize.cpp:1824
uint8_t _getMemory(uint8_t address)
Returns the contents of memory address.
Definition: AllWize.cpp:1343
void sleep()
Sets the radio module in sleep mode.
Definition: AllWize.cpp:268
String getFirmwareVersion()
Returns the module firmware revision.
Definition: AllWize.cpp:1096
bool _cacheMemory(uint8_t *buffer)
Reads and caches the module memory.
Definition: AllWize.cpp:1256
void _niceDelay(uint32_t ms)
Does a non-blocking delay.
Definition: AllWize.cpp:1872
bool _setConfig(bool value)
Sets or unsets config mode.
Definition: AllWize.cpp:1178
double getFrequency(uint8_t channel)
Returns the frequency for the given channel.
Definition: AllWize.cpp:1135
String getMID()
Returns the Manufacturer ID.
Definition: AllWize.cpp:1008
void setChannel(uint8_t channel, bool persist=false)
Sets the communications channel (for MBUS_MODE_R2 only)
Definition: AllWize.cpp:583
void _init()
Definition: AllWize.cpp:75
void setAppendRSSI(bool value)
Sets the RSSI mode value.
Definition: AllWize.cpp:708
uint8_t wize_application
Definition: AllWize.h:67
String _hw
Definition: AllWize.h:273
String getSerialNumber()
Returns the module serial number.
Definition: AllWize.cpp:1104
uint8_t type
Definition: AllWize.h:58
void getDefaultKey(uint8_t *key)
Gets the default encryption key.
Definition: AllWize.cpp:915
#define RX_BUFFER_SIZE
Definition: AllWize.h:45
void _readModel()
Searches for the module model.
Definition: AllWize.cpp:1271
uint8_t getMode()
Gets the MBus mode stored in non-volatile memory.
Definition: AllWize.cpp:684
uint8_t getControlInformation()
Gets the control information byte.
Definition: AllWize.cpp:574
uint8_t _module
Definition: AllWize.h:264
void setDataInterface(uint8_t value)
Sets the data interface for receiving packets.
Definition: AllWize.cpp:799
int _timedRead()
Reads a byte from the stream with a timeout.
Definition: AllWize.cpp:1764
void setKey(uint8_t reg, const uint8_t *key)
Sets the default encryption key.
Definition: AllWize.cpp:895
void setDefaultKey(const uint8_t *key)
Sets the default encryption key.
Definition: AllWize.cpp:907
uint8_t getInstallMode()
Gets the install modevalue stored in non-volatile memory.
Definition: AllWize.cpp:852
void setAccessNumber(uint8_t value)
Sets new/specific access number.
Definition: AllWize.cpp:923
SoftwareSerial * _sw_serial
Definition: AllWize.h:250
#define CI_APP_RESPONSE_UP_SHORT
Definition: OMS.h:34
bool reset()
Resets the radio module.
Definition: AllWize.cpp:162
uint8_t _reset_gpio
Definition: AllWize.h:253
bool _setSlot(uint8_t slot, uint8_t data)
Sets non-volatile memory contents starting from given address.
Definition: AllWize.cpp:1454
bool setMID(uint16_t mid)
Sets the Manufacturer ID.
Definition: AllWize.cpp:1016
float getRSSI()
Returns the RSSI of the last valid packet received TODO: values do not seem right and are not the sam...
Definition: AllWize.cpp:965
bool _append_rssi
Definition: AllWize.h:262
void _bin2hex(uint8_t *bin, char *hex, uint8_t len)
Converts a binary buffer to an hex c-string.
Definition: AllWize.cpp:1861
uint8_t _memory[0x100]
Definition: AllWize.h:269
uint8_t _getAddress(uint8_t slot)
Return the physical memory address for the given slot.
Definition: AllWize.cpp:1426
Stream * _stream
Definition: AllWize.h:243
uint8_t _send(uint8_t *buffer, uint8_t len)
Sends a binary buffer to the module UART. Returns the number of bytes actually sent.
Definition: AllWize.cpp:1719
bool _setMemory(uint8_t address, uint8_t data)
Sets non-volatile memory contents starting from given address.
Definition: AllWize.cpp:1361
uint16_t getTimeout()
Gets the current buffer timeout (also used for auto sleep modes)
Definition: AllWize.cpp:757
void _hex2bin(char *hex, uint8_t *bin, uint8_t len)
Converts a hex c-string to a binary buffer.
Definition: AllWize.cpp:1848
uint16_t getDataRateSpeed(uint8_t dr)
Returns the speed for te given datarate.
Definition: AllWize.cpp:1160
void _flush()
Flushes the serial line to the module.
Definition: AllWize.cpp:1685
void setWizeNetworkId(uint16_t wize_network_id)
Sets the wize network ID field in the transpoprt layer.
Definition: AllWize.cpp:530
uint8_t getDataInterface()
Gets the data interface for receiving packets.
Definition: AllWize.cpp:810
void setDataRate(uint8_t dr)
Sets the data rate.
Definition: AllWize.cpp:628
void setBaudRate(uint8_t baudrate)
Sets the UART baud rate, requires reset to take effect.
Definition: AllWize.cpp:931
HardwareSerial * _hw_serial
Definition: AllWize.h:244
uint8_t getDataRate()
Gets the data rate stored in non-volatile memory.
Definition: AllWize.cpp:653
allwize_message_t read()
Returns latest received message.
Definition: AllWize.cpp:503
void setDevice(uint8_t type)
Sets the device type.
Definition: AllWize.cpp:1072
uint8_t getBaudRate()
Gets the UART baud rate.
Definition: AllWize.cpp:942
uint8_t _mbus_mode
Definition: AllWize.h:260
uint8_t _config_gpio
Definition: AllWize.h:254
uint16_t getVoltage()
Returns the internal voltage of the module.
Definition: AllWize.cpp:992
bool factoryReset()
Resets the module to factory settings.
Definition: AllWize.cpp:212
uint8_t _ci
Definition: AllWize.h:259