AllWize Library
AllWize.h
Go to the documentation of this file.
1 /*
2 
3 AllWize Library
4 
5 Copyright (C) 2018-2019 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  uint16_t wize_operator_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_operator_id);
187  void setWizeApplication(uint8_t wize_application);
188  void setCounter(uint16_t counter);
189  uint16_t getCounter();
190 
191  protected:
192 
193  void _init();
194 
195  uint8_t _getAddress(uint8_t slot);
196  bool _setConfig(bool value);
197  int8_t _sendCommand(uint8_t command, uint8_t * data, uint8_t len);
198  int8_t _sendCommand(uint8_t command, uint8_t data);
199  int8_t _sendCommand(uint8_t command);
200 
201  bool _cacheMemory(uint8_t * buffer);
202  uint8_t _getMemory(uint8_t address);
203  uint8_t _getMemory(uint8_t address, uint8_t *buffer, uint8_t len);
204  bool _setMemory(uint8_t address, uint8_t data);
205  bool _setMemory(uint8_t address, uint8_t * data, uint8_t len);
206 
207  bool _setSlot(uint8_t slot, uint8_t data);
208  bool _setSlot(uint8_t slot, uint8_t * data, uint8_t len);
209  uint8_t _getSlot(uint8_t slot);
210  uint8_t _getSlot(uint8_t slot, uint8_t * buffer, uint8_t len);
211  String _getSlotAsHexString(uint8_t slot, uint8_t len);
212  String _getSlotAsString(uint8_t slot, uint8_t len);
213 
214  void _readModel();
215  bool _decode();
216 
217  void _flush();
218  void _reset_serial();
219  uint8_t _send(uint8_t * buffer, uint8_t len);
220  uint8_t _send(uint8_t ch);
221  int8_t _receive();
222  int8_t _sendAndReceive(uint8_t * buffer, uint8_t len);
223  int8_t _sendAndReceive(uint8_t ch);
224 
225  int _timedRead();
226  int _readBytes(char * buffer, uint16_t len);
227  int _readBytesUntil(char terminator, char * buffer, uint16_t len);
228  void _hex2bin(char * hex, uint8_t * bin, uint8_t len);
229  void _bin2hex(uint8_t * bin, char * hex, uint8_t len);
230 
231  private:
232 
233  // -------------------------------------------------------------------------
234 
235  protected:
236 
237  int8_t _rx = -1;
238  int8_t _tx = -1;
239 
240  Stream * _stream = NULL;
241  HardwareSerial * _hw_serial = NULL;
242  #if defined(ARDUINO_ARCH_SAMD)
243  // Uart * _sw_serial = NULL;
244  #elif defined(ARDUINO_ARCH_ESP32)
245  // Nothing
246  #else
247  SoftwareSerial * _sw_serial = NULL;
248  #endif
249 
252  bool _config = false;
254  uint32_t _baudrate = 19200;
255 
257  uint8_t _mbus_mode = 0xFF;
258  uint8_t _data_interface = 0xFF;
259  bool _append_rssi = false;
260  uint8_t _access_number = 0;
262 
263  // Memory buffer
264  #if USE_MEMORY_CACHE
265  bool _ready = false;
266  uint8_t _memory[0x100] = {0xFF};
267  #endif
268 
269  String _model;
270  String _hw;
271  String _fw;
272 
273  // Wize specific
274  uint8_t _wize_control = 0x00;
275  uint16_t _wize_operator_id = 0;
276  uint8_t _wize_application = 0;
277  uint16_t _counter = 0;
278 
279  // Message buffers
282  uint8_t _pointer = 0;
283 
284 };
285 
286 #endif // ALLWIZE_H
uint8_t _data_interface
Definition: AllWize.h:258
String getModuleTypeName()
Returns the module type.
Definition: AllWize.cpp:1113
uint8_t _access_number
Definition: AllWize.h:260
uint8_t getChannel()
Gets the channel stored in non-volatile memory.
Definition: AllWize.cpp:591
#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:832
uint8_t rssi
Definition: AllWize.h:63
bool enableRX(bool enable)
Enables or disables RF recever.
Definition: AllWize.cpp:443
uint16_t wize_operator_id
Definition: AllWize.h:65
uint8_t version
Definition: AllWize.h:59
String _model
Definition: AllWize.h:269
bool setUID(uint32_t uid)
Saved the UID into the module memory.
Definition: AllWize.cpp:1028
bool ack()
Sends an ACK.
Definition: AllWize.cpp:432
void setEncryptFlag(uint8_t flag)
Sets the encrypt flag setting.
Definition: AllWize.cpp:853
uint8_t getSleepMode()
Gets the sleep mode stored in non-volatile memory.
Definition: AllWize.cpp:693
uint8_t getLEDControl()
Gets the current LED control.
Definition: AllWize.cpp:784
uint8_t getPower()
Gets the RF power stored in non-volatile memory.
Definition: AllWize.cpp:613
uint8_t len
Definition: AllWize.h:61
void setWizeOperatorId(uint16_t wize_operator_id)
Sets the wize operator ID field in the transpoprt layer.
Definition: AllWize.cpp:523
String _fw
Definition: AllWize.h:271
int _readBytes(char *buffer, uint16_t len)
Reads the stream buffer up to a number of bytes.
Definition: AllWize.cpp:1796
void setWizeApplication(uint8_t wize_application)
Sets the wize applicaton field in the transpoprt layer.
Definition: AllWize.cpp:531
uint8_t getEncryptFlag()
Gets the encrypt flag setting.
Definition: AllWize.cpp:863
void setVersion(uint8_t version)
Sets the device version.
Definition: AllWize.cpp:1049
void slave()
Sets the module in slave mode.
Definition: AllWize.cpp:249
allwize_message_t _message
Definition: AllWize.h:280
void setPower(uint8_t power, bool persist=false)
Sets the RF power.
Definition: AllWize.cpp:600
void setNetworkRole(uint8_t role)
Sets the network role.
Definition: AllWize.cpp:759
uint8_t _wize_application
Definition: AllWize.h:276
uint32_t getBaudRateSpeed(uint8_t value)
Gets the UART baud rate speed in bps.
Definition: AllWize.cpp:944
bool getAppendRSSI()
Gets the current RSSI mode value.
Definition: AllWize.cpp:714
bool _decode()
Decodes the current RX buffer contents.
Definition: AllWize.cpp:1542
uint8_t getVersion()
Returns the device version from non-volatile memory.
Definition: AllWize.cpp:1041
void setControlField(uint8_t value, bool persist=false)
Sets the control field value.
Definition: AllWize.cpp:812
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:1200
void setMode(uint8_t mode, bool persist=false)
Sets the module in one of the available MBus modes.
Definition: AllWize.cpp:655
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:1081
void setPreamble(uint8_t preamble)
Sets the preamble length frame format.
Definition: AllWize.cpp:722
uint8_t getControlField()
Gets the control field value stored in non-volatile memory.
Definition: AllWize.cpp:823
uint16_t _counter
Definition: AllWize.h:277
uint8_t getPreamble()
Gets the preamble length frame format.
Definition: AllWize.cpp:732
int8_t _receive()
Listens to incoming data from the module until timeout or END_OF_RESPONSE.
Definition: AllWize.cpp:1728
uint16_t _wize_operator_id
Definition: AllWize.h:275
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:539
void softReset()
Cleans the RX/TX line.
Definition: AllWize.cpp:197
bool _ready
Definition: AllWize.h:265
uint8_t _getSlot(uint8_t slot)
Returns the contents of single-byte memory slot.
Definition: AllWize.cpp:1473
uint8_t _buffer[RX_BUFFER_SIZE]
Definition: AllWize.h:281
String getUID()
Returns the Unique ID string.
Definition: AllWize.cpp:1020
uint16_t wize_counter
Definition: AllWize.h:66
uint8_t getTemperature()
Returns the internal temperature of the module.
Definition: AllWize.cpp:968
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:685
uint8_t getDecryptFlag()
Gets the decrypt flag setting.
Definition: AllWize.cpp:879
void setControlInformation(uint8_t ci)
Sets the control information byte.
Definition: AllWize.cpp:559
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:458
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:1486
uint8_t getDevice()
Returns the device type from non-volatile memory.
Definition: AllWize.cpp:1057
void setLEDControl(uint8_t value)
Sets the LED control.
Definition: AllWize.cpp:775
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:1739
uint8_t _pointer
Definition: AllWize.h:282
void setDecryptFlag(uint8_t flag)
Sets the decrypt flag setting.
Definition: AllWize.cpp:871
uint32_t _baudrate
Definition: AllWize.h:254
#define DEFAULT_TIMEOUT
Definition: AllWize.h:46
String getPartNumber()
Returns the module part number.
Definition: AllWize.cpp:1073
uint8_t _wize_control
Definition: AllWize.h:274
uint8_t ci
Definition: AllWize.h:56
uint8_t getModuleType()
Returns the module type.
Definition: AllWize.cpp:1105
void _reset_serial()
Resets the serial object.
Definition: AllWize.cpp:120
#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:740
uint8_t getNetworkRole()
Gets the current network role.
Definition: AllWize.cpp:767
bool setWizeControl(uint8_t wize_control)
Sets the wize control field in the transpoprt layer.
Definition: AllWize.cpp:513
uint8_t wize_control
Definition: AllWize.h:64
bool _config
Definition: AllWize.h:252
int8_t _tx
Definition: AllWize.h:238
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:1503
int8_t _rx
Definition: AllWize.h:237
uint32_t _timeout
Definition: AllWize.h:253
uint16_t getCounter()
Gets the current wize counter.
Definition: AllWize.cpp:547
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:1820
uint8_t _getMemory(uint8_t address)
Returns the contents of memory address.
Definition: AllWize.cpp:1336
void sleep()
Sets the radio module in sleep mode.
Definition: AllWize.cpp:268
String getFirmwareVersion()
Returns the module firmware revision.
Definition: AllWize.cpp:1089
bool _cacheMemory(uint8_t *buffer)
Reads and caches the module memory.
Definition: AllWize.cpp:1249
bool _setConfig(bool value)
Sets or unsets config mode.
Definition: AllWize.cpp:1171
double getFrequency(uint8_t channel)
Returns the frequency for the given channel.
Definition: AllWize.cpp:1128
String getMID()
Returns the Manufacturer ID.
Definition: AllWize.cpp:1001
void setChannel(uint8_t channel, bool persist=false)
Sets the communications channel (for MBUS_MODE_R2 only)
Definition: AllWize.cpp:576
void _init()
Definition: AllWize.cpp:75
void setAppendRSSI(bool value)
Sets the RSSI mode value.
Definition: AllWize.cpp:701
uint8_t wize_application
Definition: AllWize.h:67
String _hw
Definition: AllWize.h:270
String getSerialNumber()
Returns the module serial number.
Definition: AllWize.cpp:1097
uint8_t type
Definition: AllWize.h:58
void getDefaultKey(uint8_t *key)
Gets the default encryption key.
Definition: AllWize.cpp:908
#define RX_BUFFER_SIZE
Definition: AllWize.h:45
void _readModel()
Searches for the module model.
Definition: AllWize.cpp:1264
uint8_t getMode()
Gets the MBus mode stored in non-volatile memory.
Definition: AllWize.cpp:677
uint8_t getControlInformation()
Gets the control information byte.
Definition: AllWize.cpp:567
uint8_t _module
Definition: AllWize.h:261
void setDataInterface(uint8_t value)
Sets the data interface for receiving packets.
Definition: AllWize.cpp:792
int _timedRead()
Reads a byte from the stream with a timeout.
Definition: AllWize.cpp:1760
void setKey(uint8_t reg, const uint8_t *key)
Sets the default encryption key.
Definition: AllWize.cpp:888
void setDefaultKey(const uint8_t *key)
Sets the default encryption key.
Definition: AllWize.cpp:900
uint8_t getInstallMode()
Gets the install modevalue stored in non-volatile memory.
Definition: AllWize.cpp:845
void setAccessNumber(uint8_t value)
Sets new/specific access number.
Definition: AllWize.cpp:916
SoftwareSerial * _sw_serial
Definition: AllWize.h:247
#define CI_APP_RESPONSE_UP_SHORT
Definition: OMS.h:28
bool reset()
Resets the radio module.
Definition: AllWize.cpp:162
uint8_t _reset_gpio
Definition: AllWize.h:250
bool _setSlot(uint8_t slot, uint8_t data)
Sets non-volatile memory contents starting from given address.
Definition: AllWize.cpp:1447
bool setMID(uint16_t mid)
Sets the Manufacturer ID.
Definition: AllWize.cpp:1009
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:958
bool _append_rssi
Definition: AllWize.h:259
void _bin2hex(uint8_t *bin, char *hex, uint8_t len)
Converts a binary buffer to an hex c-string.
Definition: AllWize.cpp:1857
uint8_t _memory[0x100]
Definition: AllWize.h:266
uint8_t _getAddress(uint8_t slot)
Return the physical memory address for the given slot.
Definition: AllWize.cpp:1419
Stream * _stream
Definition: AllWize.h:240
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:1715
bool _setMemory(uint8_t address, uint8_t data)
Sets non-volatile memory contents starting from given address.
Definition: AllWize.cpp:1354
uint16_t getTimeout()
Gets the current buffer timeout (also used for auto sleep modes)
Definition: AllWize.cpp:750
void _hex2bin(char *hex, uint8_t *bin, uint8_t len)
Converts a hex c-string to a binary buffer.
Definition: AllWize.cpp:1844
uint16_t getDataRateSpeed(uint8_t dr)
Returns the speed for te given datarate.
Definition: AllWize.cpp:1153
void _flush()
Flushes the serial line to the module.
Definition: AllWize.cpp:1681
uint8_t getDataInterface()
Gets the data interface for receiving packets.
Definition: AllWize.cpp:803
void setDataRate(uint8_t dr)
Sets the data rate.
Definition: AllWize.cpp:621
void setBaudRate(uint8_t baudrate)
Sets the UART baud rate, requires reset to take effect.
Definition: AllWize.cpp:924
HardwareSerial * _hw_serial
Definition: AllWize.h:241
uint8_t getDataRate()
Gets the data rate stored in non-volatile memory.
Definition: AllWize.cpp:646
allwize_message_t read()
Returns latest received message.
Definition: AllWize.cpp:504
void setDevice(uint8_t type)
Sets the device type.
Definition: AllWize.cpp:1065
uint8_t getBaudRate()
Gets the UART baud rate.
Definition: AllWize.cpp:935
uint8_t _mbus_mode
Definition: AllWize.h:257
uint8_t _config_gpio
Definition: AllWize.h:251
uint16_t getVoltage()
Returns the internal voltage of the module.
Definition: AllWize.cpp:985
bool factoryReset()
Resets the module to factory settings.
Definition: AllWize.cpp:212
uint8_t _ci
Definition: AllWize.h:256