AllWize Library
AllWize.h
1 /*
2 
3 AllWize Library
4 
5 Copyright (C) 2018 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 
26 #ifndef ALLWIZE_H
27 #define ALLWIZE_H
28 
29 #include <Arduino.h>
30 #include "Wize.h"
31 #include <Stream.h>
32 #if not defined(ARDUINO_ARCH_SAMD) && not defined(ARDUINO_ARCH_ESP32)
33 #include <SoftwareSerial.h>
34 #endif
35 
36 // -----------------------------------------------------------------------------
37 // Types & definitions
38 // -----------------------------------------------------------------------------
39 
40 // General
41 #define MODEM_BAUDRATE 19200
42 #define GPIO_NONE 0x99
43 #define CONTROL_INFORMATION 0x67
44 #define END_OF_RESPONSE '>'
45 #define CMD_ENTER_CONFIG (char) 0x00
46 #define CMD_EXIT_CONFIG (char) 0x58
47 #define CMD_EXIT_MEMORY_ENABLE_RF (char) 0xFD
48 #define CMD_EXIT_MEMORY_DISABLE_RF (char) 0xFF
49 #define CMD_AWAKE (char) 0xFF // Deprecated
50 #define CMD_EXIT_MEMORY (char) 0xFF
51 #define RX_BUFFER_SIZE 255
52 #define DEFAULT_TIMEOUT 1000
53 #define HARDWARE_SERIAL_PORT 1
54 #define SIGNATURE_FIELD 0x04 // TODO: should not be here
55 #define START_BYTE 0x68
56 #define STOP_BYTE 0x16
57 #define DEFAULT_MBUS_MODE MBUS_MODE_N1
58 
59 typedef struct {
60  uint8_t c;
61  uint8_t ci;
62  char man[4];
63  uint8_t type;
64  uint8_t version;
65  uint8_t address[4];
66  uint8_t len;
67  uint8_t data[RX_BUFFER_SIZE];
68  uint8_t rssi;
70 
71 // -----------------------------------------------------------------------------
72 // DEBUG
73 // -----------------------------------------------------------------------------
74 
75 // Uncomment this to the proper port
76 // or define it in your build settings if you want
77 // to get low level debug information via serial
78 //#define ALLWIZE_DEBUG_PORT Serial
79 
80 #if defined(ALLWIZE_DEBUG_PORT)
81  #define ALLWIZE_DEBUG_PRINT(...) ALLWIZE_DEBUG_PORT.print(__VA_ARGS__)
82  #define ALLWIZE_DEBUG_PRINTLN(...) ALLWIZE_DEBUG_PORT.println(__VA_ARGS__)
83 #else
84  #define ALLWIZE_DEBUG_PRINT(...)
85  #define ALLWIZE_DEBUG_PRINTLN(...)
86 #endif
87 
88 // -----------------------------------------------------------------------------
89 // Class prototype
90 // -----------------------------------------------------------------------------
91 
92 class AllWize {
93 
94  public:
95 
96  AllWize(HardwareSerial * serial, uint8_t reset_gpio = GPIO_NONE);
97  #if not defined(ARDUINO_ARCH_SAMD) && not defined(ARDUINO_ARCH_ESP32)
98  AllWize(SoftwareSerial * serial, uint8_t reset_gpio = GPIO_NONE);
99  #endif
100  AllWize(uint8_t rx, uint8_t tx, uint8_t reset_gpio = GPIO_NONE);
101 
102  void begin();
103  bool reset();
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 send(uint8_t * buffer, uint8_t len);
112  bool send(const char * buffer);
113  bool available();
115 
116  void setControlInformation(uint8_t ci);
117  uint8_t getControlInformation();
118 
119  void master();
120  void slave();
121  void repeater();
122 
123  void setChannel(uint8_t channel, bool persist = false);
124  void setPower(uint8_t power, bool persist = false);
125  void setDataRate(uint8_t dr);
126  void setMode(uint8_t mode, bool persist = false);
127  void setSleepMode(uint8_t mode);
128  void setAppendRSSI(bool value);
129  void setPreamble(uint8_t preamble);
130  void setTimeout(uint8_t timeout);
131  void setNetworkRole(uint8_t role);
132  void setLEDControl(uint8_t value);
133  void setDataInterface(uint8_t value);
134  void setControlField(uint8_t value, bool persist = false);
135  void setInstallMode(uint8_t mode, bool persist = false);
136  void setEncryptFlag(uint8_t flag);
137  void setDecryptFlag(uint8_t flag);
138  void setKey(uint8_t reg, const uint8_t * key);
139  void setDefaultKey(const uint8_t * key);
140 
141  uint8_t getChannel();
142  uint8_t getPower();
143  uint8_t getDataRate();
144  uint8_t getMode();
145  uint8_t getSleepMode();
146  uint8_t getPreamble();
147  uint8_t getDataInterface();
148  uint8_t getControlField();
149  bool getAppendRSSI();
150  uint8_t getTimeout();
151  uint8_t getNetworkRole();
152  uint8_t getLEDControl();
153  uint8_t getInstallMode();
154  uint8_t getEncryptFlag();
155  uint8_t getDecryptFlag();
156  void getDefaultKey(uint8_t * key);
157 
158  //float getRSSI();
159  uint8_t getTemperature();
160  uint16_t getVoltage();
161  String getMID();
162  bool setMID(uint16_t mid);
163  String getUID();
164  bool setUID(uint32_t uid);
165  uint8_t getVersion();
166  uint8_t getDevice();
167  String getPartNumber();
169  String getFirmwareVersion();
170  String getSerialNumber();
171 
172  protected:
173 
174  void _init();
175 
176  bool _setConfig(bool value);
177  int8_t _sendCommand(uint8_t command, uint8_t * data, uint8_t len);
178  int8_t _sendCommand(uint8_t command, uint8_t data);
179  int8_t _sendCommand(uint8_t command);
180  bool _setMemory(uint8_t address, uint8_t * data, uint8_t len);
181  bool _setMemory(uint8_t address, uint8_t data);
182  uint8_t _getMemory(uint8_t address, uint8_t * buffer, uint8_t len);
183  uint8_t _getMemory(uint8_t address);
184  String _getMemoryAsHexString(uint8_t address, uint8_t len);
185  String _getMemoryAsString(uint8_t address, uint8_t len);
186  void _readModel();
187 
188  bool _decode();
189 
190  void _flush();
191  void _reset_serial();
192  uint8_t _send(uint8_t * buffer, uint8_t len);
193  uint8_t _send(uint8_t ch);
194  int8_t _receive();
195  int8_t _sendAndReceive(uint8_t * buffer, uint8_t len);
196  int8_t _sendAndReceive(uint8_t ch);
197 
198  int _timedRead();
199  int _readBytes(char * buffer, uint16_t len);
200  int _readBytesUntil(char terminator, char * buffer, uint16_t len);
201  void _hex2bin(char * hex, uint8_t * bin, uint8_t len);
202  void _bin2hex(uint8_t * bin, char * hex, uint8_t len);
203 
204  private:
205 
206  // -------------------------------------------------------------------------
207 
208  protected:
209 
210  int8_t _rx = -1;
211  int8_t _tx = -1;
212 
213  Stream * _stream = NULL;
214  HardwareSerial * _hw_serial = NULL;
215  #if defined(ARDUINO_ARCH_SAMD)
216  // Uart * _sw_serial = NULL;
217  #elif defined(ARDUINO_ARCH_ESP32)
218  // Nothing
219  #else
220  SoftwareSerial * _sw_serial = NULL;
221  #endif
222 
223  uint8_t _reset_gpio = GPIO_NONE;
224  bool _config = false;
225  uint32_t _timeout = DEFAULT_TIMEOUT;
226  uint8_t _ci = CONTROL_INFORMATION;
227 
228  uint8_t _mbus_mode = 0xFF;
229  uint8_t _data_interface = 0xFF;
230  bool _append_rssi = false;
231 
232 
233  bool _encrypt = false;
234  unsigned char _access_number = 0;
235 
236  String _model;
237  String _fw;
238  String _hw;
239 
240  allwize_message_t _message;
241 
242  uint8_t _buffer[RX_BUFFER_SIZE];
243  uint8_t _pointer;
244 
245 };
246 
247 #endif // ALLWIZE_H
uint8_t getChannel()
Gets the channel stored in non-volatile memory.
Definition: AllWize.cpp:407
void setInstallMode(uint8_t mode, bool persist=false)
Sets the module in one of the available operations modes.
Definition: AllWize.cpp:619
bool setUID(uint32_t uid)
Saved the UID into the module memory uid UID to save.
Definition: AllWize.cpp:780
void setEncryptFlag(uint8_t flag)
Sets the encrypt flag setting.
Definition: AllWize.cpp:640
uint8_t getSleepMode()
Gets the sleep mode stored in non-volatile memory.
Definition: AllWize.cpp:484
uint8_t getLEDControl()
Gets the current LED control.
Definition: AllWize.cpp:571
uint8_t getPower()
Gets the RF power stored in non-volatile memory.
Definition: AllWize.cpp:429
int _readBytes(char *buffer, uint16_t len)
Reads the stream buffer up to a number of bytes.
Definition: AllWize.cpp:1283
bool _setMemory(uint8_t address, uint8_t *data, uint8_t len)
Sets non-volatile memory contents starting from given address.
Definition: AllWize.cpp:923
uint8_t getEncryptFlag()
Gets the encrypt flag setting.
Definition: AllWize.cpp:651
AllWize(HardwareSerial *serial, uint8_t reset_gpio=GPIO_NONE)
AllWize object constructor.
Definition: AllWize.cpp:34
void slave()
Sets the module in slave mode.
Definition: AllWize.cpp:192
void setPower(uint8_t power, bool persist=false)
Sets the RF power.
Definition: AllWize.cpp:416
void setNetworkRole(uint8_t role)
Sets the network role.
Definition: AllWize.cpp:547
String _getMemoryAsHexString(uint8_t address, uint8_t len)
Returns the contents of the memory from a certain address as an HEX String.
Definition: AllWize.cpp:986
bool getAppendRSSI()
Gets the current RSSI mode value.
Definition: AllWize.cpp:505
bool _decode()
Decodes the current RX buffer contents.
Definition: AllWize.cpp:1071
uint8_t getVersion()
Returns the module version from non-volatile memory.
Definition: AllWize.cpp:793
void setControlField(uint8_t value, bool persist=false)
Sets the control field value.
Definition: AllWize.cpp:599
int8_t _sendCommand(uint8_t command, uint8_t *data, uint8_t len)
Sends a command with the given data.
Definition: AllWize.cpp:874
void dump(Stream &debug)
Dumps the current memory configuration to the given stream.
Definition: AllWize.cpp:248
void setMode(uint8_t mode, bool persist=false)
Sets the module in one of the available MBus modes.
Definition: AllWize.cpp:456
void setPreamble(uint8_t preamble)
Sets the preamble length frame format.
Definition: AllWize.cpp:513
uint8_t getControlField()
Gets the control field value stored in non-volatile memory.
Definition: AllWize.cpp:610
uint8_t getTimeout()
Gets the current timeout for auto sleep modes.
Definition: AllWize.cpp:539
uint8_t getPreamble()
Gets the preamble length frame format.
Definition: AllWize.cpp:523
int8_t _receive()
Listens to incomming data from the module until timeout or END_OF_RESPONSE.
Definition: AllWize.cpp:1228
bool send(uint8_t *buffer, uint8_t len)
Sends a byte array.
Definition: AllWize.cpp:301
String getUID()
Returns the Unique ID string.
Definition: AllWize.cpp:772
uint8_t getTemperature()
Returns the RSSI of the last valid packet received TODO: values do not seem right and are not the sam...
Definition: AllWize.cpp:720
bool ready()
Test whether the radio module is ready or not.
Definition: AllWize.cpp:226
void setSleepMode(uint8_t mode)
Sets the sleep mode.
Definition: AllWize.cpp:476
uint8_t getDecryptFlag()
Gets the decrypt flag setting.
Definition: AllWize.cpp:667
void setControlInformation(uint8_t ci)
Sets the control information byte.
Definition: AllWize.cpp:379
void wakeup()
Wakes up the radio from sleep mode.
Definition: AllWize.cpp:218
void master()
Sets the module in master mode.
Definition: AllWize.cpp:178
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:334
uint8_t getDevice()
Returns the device version from non-volatile memory.
Definition: AllWize.cpp:801
void setLEDControl(uint8_t value)
Sets the LED control.
Definition: AllWize.cpp:563
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:1239
void setTimeout(uint8_t timeout)
Sets the timeout for auto sleep modes.
Definition: AllWize.cpp:531
uint8_t _getMemory(uint8_t address, uint8_t *buffer, uint8_t len)
Returns the contents of consecutive memory addresses.
Definition: AllWize.cpp:953
void setDecryptFlag(uint8_t flag)
Sets the decrypt flag setting.
Definition: AllWize.cpp:659
String getPartNumber()
Returns the module part number.
Definition: AllWize.cpp:809
void _reset_serial()
Resets the serial object.
Definition: AllWize.cpp:90
void repeater()
Sets the module in repeater mode.
Definition: AllWize.cpp:202
bool waitForReady(uint32_t timeout=DEFAULT_TIMEOUT)
Waits for timeout millis for the module to be ready.
Definition: AllWize.cpp:235
uint8_t getNetworkRole()
Gets the current network role.
Definition: AllWize.cpp:555
uint8_t getMode()
Gets the MBus mode stored in non-volatile memory.
Definition: AllWize.cpp:468
int _readBytesUntil(char terminator, char *buffer, uint16_t len)
Reads the stream buffer up to a certain char or times out.
Definition: AllWize.cpp:1312
void sleep()
Sets the radio module in sleep mode.
Definition: AllWize.cpp:210
String getFirmwareVersion()
Returns the module firmware revision.
Definition: AllWize.cpp:827
bool _setConfig(bool value)
Sets or unsets config mode.
Definition: AllWize.cpp:850
String getMID()
Returns the Manufacturer ID string.
Definition: AllWize.cpp:753
void setChannel(uint8_t channel, bool persist=false)
Sets the communications channel (for MBUS_MODE_R2 only)
Definition: AllWize.cpp:396
void setAppendRSSI(bool value)
Sets the RSSI mode value.
Definition: AllWize.cpp:492
String getSerialNumber()
Returns the module serial number.
Definition: AllWize.cpp:836
void getDefaultKey(uint8_t *key)
Gets the default encryption key.
Definition: AllWize.cpp:697
String _getMemoryAsString(uint8_t address, uint8_t len)
Returns the contents of the memory from a certain address as a String object.
Definition: AllWize.cpp:1003
void _readModel()
Reads and caches the module model & version.
Definition: AllWize.cpp:1017
uint8_t getControlInformation()
Gets the control information byte.
Definition: AllWize.cpp:387
void setDataInterface(uint8_t value)
Sets the data interface for receiving packets.
Definition: AllWize.cpp:579
int _timedRead()
Reads a byte from the stream with a timeout.
Definition: AllWize.cpp:1264
void setKey(uint8_t reg, const uint8_t *key)
Sets the default encryption key.
Definition: AllWize.cpp:676
void setDefaultKey(const uint8_t *key)
Sets the default encryption key.
Definition: AllWize.cpp:689
uint8_t getInstallMode()
Gets the install modevalue stored in non-volatile memory.
Definition: AllWize.cpp:632
bool reset()
Resets the radio module.
Definition: AllWize.cpp:127
bool setMID(uint16_t mid)
Sets the Manufacturer ID mid MID to save.
Definition: AllWize.cpp:761
String getRequiredHardwareVersion()
Returns the module hardware revision.
Definition: AllWize.cpp:818
void _bin2hex(uint8_t *bin, char *hex, uint8_t len)
Converts a binary buffer to an hex c-string.
Definition: AllWize.cpp:1355
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:1215
void begin()
Inits the module communications.
Definition: AllWize.cpp:79
void _hex2bin(char *hex, uint8_t *bin, uint8_t len)
Converts a hex c-string to a binary buffer.
Definition: AllWize.cpp:1342
void _flush()
Flushes the serial line to the module.
Definition: AllWize.cpp:1187
uint8_t getDataInterface()
Gets the data interface for receiving packets.
Definition: AllWize.cpp:590
void setDataRate(uint8_t dr)
Sets the data rate.
Definition: AllWize.cpp:437
uint8_t getDataRate()
Gets the data rate stored in non-volatile memory.
Definition: AllWize.cpp:447
allwize_message_t read()
Returns latest received message.
Definition: AllWize.cpp:367
uint16_t getVoltage()
Returns the internal voltage of the module.
Definition: AllWize.cpp:737
bool factoryReset()
Resets the module to factory settings.
Definition: AllWize.cpp:158