Allwize Library
Allwize.h
1 /*
2 
3 Allwize 0.0.1
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 <Stream.h>
31 
32 // -----------------------------------------------------------------------------
33 // Types & definitions
34 // -----------------------------------------------------------------------------
35 
36 // General
37 #define MODEM_BAUDRATE 19200
38 #define CONTROL_INFORMATION 0x7A
39 #define END_OF_RESPONSE '>'
40 #define CMD_ENTER_CONFIG (char) 0x00
41 #define CMD_EXIT_CONFIG (char) 0x58
42 #define CMD_EXIT_MEMORY (char) 0xFF
43 #define RX_BUFFER_SIZE 255
44 #define DEFAULT_TIMEOUT 1000
45 
46 // Command keys
47 #define CMD_CHANNEL 'C'
48 #define CMD_CONTROL_FIELD 'F'
49 #define CMD_MBUS_MODE 'G'
50 #define CMD_INSTALL_MODE 'I'
51 #define CMD_WRITE_MEMORY 'M'
52 #define CMD_RF_POWER 'P'
53 #define CMD_QUALITY 'Q'
54 #define CMD_RSSI 'S'
55 #define CMD_TEMPERATURE 'U'
56 #define CMD_VOLTAGE 'V'
57 #define CMD_READ_MEMORY 'Y'
58 #define CMD_SLEEP 'Z'
59 
60 // Memory addresses
61 #define MEM_CHANNEL 0x00
62 #define MEM_RF_POWER 0x01
63 #define MEM_DATA_RATE 0x02
64 #define MEM_MBUS_MODE 0x03
65 #define MEM_SLEEP_MODE 0x04
66 #define MEM_RSSI_MODE 0x05
67 #define MEM_PREAMBLE_LENGTH 0x0A
68 #define MEM_TIMEOUT 0x10
69 #define MEM_NETWORK_ROLE 0x12
70 #define MEM_MAILBOX 0x16
71 #define MEM_MANUFACTURER_ID 0x19
72 #define MEM_UNIQUE_ID 0x1B
73 #define MEM_VERSION 0x1F
74 #define MEM_DEVICE 0x20
75 #define MEM_UART_BAUD_RATE 0x30
76 #define MEM_UART_FLOW_CTRL 0x35
77 #define MEM_DATA_INTERFACE 0x36
78 #define MEM_CONFIG_INTERFACE 0x37
79 #define MEM_FREQ_CAL 0x39
80 #define MEM_LED_CONTROL 0x3A
81 #define MEM_CONTROL_FIELD 0x3B
82 #define MEM_RX_TIMEOUT 0x3C
83 #define MEM_INSTALL_MODE 0x3D
84 #define MEM_ENCRYPT_FLAG 0x3E
85 #define MEM_DECRYPT_FLAG 0x3F
86 #define MEM_DEFAULT_KEY 0x40
87 #define MEM_PART_NUMBER_OLD 0x61
88 #define MEM_SERIAL_NUMBER_OLD 0x71
89 #define MEM_PART_NUMBER_NEW 0x89
90 #define MEM_SERIAL_NUMBER_NEW 0xA9
91 
92 // MBus modes
93 #define MBUS_MODE_S2 0x00
94 #define MBUS_MODE_T1 0x01
95 #define MBUS_MODE_T2 0x02
96 #define MBUS_MODE_S1 0x03
97 #define MBUS_MODE_R 0x04
98 #define MBUS_MODE_T1_C 0x0A
99 #define MBUS_MODE_T2_C 0x0B
100 #define MBUS_MODE_N2 0x10
101 #define MBUS_MODE_N1 0x11
102 #define MBUS_MODE_OSP 0x12
103 
104 // Operation modes
105 #define INSTALL_MODE_NORMAL 0x00
106 #define INSTALL_MODE_INSTALL 0x01
107 #define INSTALL_MODE_HOST 0x02
108 
109 // Sleep modes
110 #define SLEEP_MODE_DISABLE 0x00
111 #define SLEEP_MODE_AFTER_TX 0x01
112 #define SLEEP_MODE_AFTER_TX_RX 0x03
113 #define SLEEP_MODE_AFTER_TX_TIMEOUT 0x05
114 #define SLEEP_MODE_AFTER_TX_RX_TIMEOUT 0x07
115 
116 // Network roles
117 #define NETWORK_ROLE_SLAVE 0x00
118 #define NETWORK_ROLE_MASTER 0x01
119 #define NETWORK_ROLE_REPEATER 0x02
120 
121 // Timeouts
122 #define TIMEOUT_32MS 0x01
123 #define TIMEOUT_48MS 0x02
124 #define TIMEOUT_64MS 0x03
125 #define TIMEOUT_2S 0x7C
126 #define TIMEOUT_4S 0xF9
127 
128 // LED Control
129 #define LED_CONTROL_DISABLED 0x00
130 #define LED_CONTROL_RX_TX 0x01
131 #define LED_CONTROL_UART_RF_IDLE 0x02
132 
133 // Encrypt/Decrypt flags
134 #define ENCRYPT_DISABLED 0x00
135 #define ENCRYPT_ENABLED 0x01
136 #define ENCRYPT_ENABLED_CRC 0x03
137 
138 // Data interface
139 #define DATA_INTERFACE_ID_ADDR 0x00
140 #define DATA_INTERFACE_APP_ONLY 0x01
141 #define DATA_INTERFACE_APP_ACK 0x03
142 #define DATA_INTERFACE_START_STOP 0x04
143 #define DATA_INTERFACE_CRC 0x08
144 #define DATA_INTERFACE_CRC_START_STOP 0x0C
145 
146 
147 // Preamble Length
148 #define PREAMBLE_FORMAT_A 0x00
149 #define PREAMBLE_FORMAT_B 0x02
150 
151 typedef struct {
152  uint8_t c;
153  uint8_t ci;
154  uint8_t len;
155  uint8_t * data;
156  uint8_t rssi;
158 
159 // -----------------------------------------------------------------------------
160 // Class prototype
161 // -----------------------------------------------------------------------------
162 
163 class Allwize {
164 
165  public:
166 
167  Allwize(Stream & stream, uint8_t reset_gpio = 0xFF);
168 
169  void begin();
170  bool reset();
171  bool factoryReset();
172  void sleep();
173  void wakeup();
174  bool ready();
175  void dump(Stream & debug);
176 
177  bool send(uint8_t * buffer, uint8_t len);
178  bool send(const char * buffer);
179  bool available();
181 
182  void setControlInformation(uint8_t ci);
183  uint8_t getControlInformation();
184 
185  void master();
186  void slave();
187  void repeater();
188 
189  void setChannel(uint8_t channel, bool persist = false);
190  void setPower(uint8_t power, bool persist = false);
191  void setDataRate(uint8_t dr);
192  void setMode(uint8_t mode, bool persist = false);
193  void setSleepMode(uint8_t mode);
194  //void setAppendRSSI(bool value);
195  void setPreamble(uint8_t preamble);
196  void setTimeout(uint8_t timeout);
197  void setNetworkRole(uint8_t role);
198  void setLEDControl(uint8_t value);
199  //void setDataInterface(uint8_t value);
200  void setControlField(uint8_t value, bool persist = false);
201  void setInstallMode(uint8_t mode, bool persist = false);
202  void setEncryptFlag(uint8_t flag);
203  void setDecryptFlag(uint8_t flag);
204  void setDefaultKey(uint8_t * key);
205 
206  uint8_t getChannel();
207  uint8_t getPower();
208  uint8_t getDataRate();
209  uint8_t getMode();
210  uint8_t getSleepMode();
211  uint8_t getPreamble();
212  //uint8_t getDataInterface();
213  uint8_t getControlField();
214  //bool getAppendRSSI();
215  uint8_t getTimeout();
216  uint8_t getNetworkRole();
217  uint8_t getLEDControl();
218  uint8_t getInstallMode();
219  uint8_t getEncryptFlag();
220  uint8_t getDecryptFlag();
221  void getDefaultKey(uint8_t * key);
222 
223  //float getRSSI();
224  uint8_t getTemperature();
225  uint16_t getVoltage();
226  String getMID();
227  String getUID();
228  uint8_t getVersion();
229  uint8_t getDevice();
230  String getPartNumber();
232  String getFirmwareVersion();
233  String getSerialNumber();
234 
235  protected:
236 
237  bool _setConfig(bool value);
238  int8_t _sendCommand(uint8_t command, uint8_t * data, uint8_t len);
239  int8_t _sendCommand(uint8_t command, uint8_t data);
240  int8_t _sendCommand(uint8_t command);
241  bool _setMemory(uint8_t address, uint8_t * data, uint8_t len);
242  bool _setMemory(uint8_t address, uint8_t data);
243  uint8_t _getMemory(uint8_t address, uint8_t * buffer, uint8_t len);
244  uint8_t _getMemory(uint8_t address);
245  String _getMemoryAsHexString(uint8_t address, uint8_t len);
246  String _getMemoryAsString(uint8_t address, uint8_t len);
247  void _readModel();
248 
249  bool _decode();
250 
251  void _flush();
252  uint8_t _send(uint8_t * buffer, uint8_t len);
253  uint8_t _send(uint8_t ch);
254  int8_t _receive();
255  int8_t _sendAndReceive(uint8_t * buffer, uint8_t len);
256  int8_t _sendAndReceive(uint8_t ch);
257 
258  int _timedRead();
259  int _readBytes(char * buffer, uint16_t len);
260  int _readBytesUntil(char terminator, char * buffer, uint16_t len);
261  void _hex2bin(char * hex, uint8_t * bin, uint8_t len);
262  void _bin2hex(uint8_t * bin, char * hex, uint8_t len);
263 
264  private:
265 
266  // -------------------------------------------------------------------------
267 
268  protected:
269 
270  Stream & _stream;
271 
272  uint8_t _reset_gpio = 0xFF;
273  bool _config = false;
274  uint32_t _timeout = DEFAULT_TIMEOUT;
275  uint8_t _ci = CONTROL_INFORMATION;
276 
277  String _model;
278  String _fw;
279  String _hw;
280 
281  allwize_message_t _message;
282 
283  uint8_t _buffer[RX_BUFFER_SIZE];
284  uint8_t _pointer;
285 
286 };
287 
288 #endif // ALLWIZE_H
String getFirmwareVersion()
Returns the module firmware revision.
Definition: Allwize.cpp:654
void _flush()
Flushes the serial line to the module.
Definition: Allwize.cpp:924
uint8_t getControlInformation()
Gets the control information byte.
Definition: Allwize.cpp:287
int8_t _sendCommand(uint8_t command, uint8_t *data, uint8_t len)
Sends a command with the given data.
Definition: Allwize.cpp:701
uint8_t _getMemory(uint8_t address, uint8_t *buffer, uint8_t len)
Returns the contents of consecutive memory addresses.
Definition: Allwize.cpp:780
void setChannel(uint8_t channel, bool persist=false)
Sets the communications channel (for MBUS_MODE_R2 only)
Definition: Allwize.cpp:296
void setDataRate(uint8_t dr)
Sets the data rate.
Definition: Allwize.cpp:333
void setSleepMode(uint8_t mode)
Sets the sleep mode.
Definition: Allwize.cpp:369
void slave()
Sets the module in slave mode.
Definition: Allwize.cpp:116
void setEncryptFlag(uint8_t flag)
Sets the encrypt flag setting.
Definition: Allwize.cpp:521
bool factoryReset()
Resets the module to factory settings You must reset the serial connection after the factoryReset: Se...
Definition: Allwize.cpp:87
uint8_t getPreamble()
Gets the preamble length frame format.
Definition: Allwize.cpp:411
void _readModel()
Reads and caches the module model & version.
Definition: Allwize.cpp:844
void setInstallMode(uint8_t mode, bool persist=false)
Sets the module in one of the available operations modes.
Definition: Allwize.cpp:504
int _readBytes(char *buffer, uint16_t len)
Reads the stream buffer up to a number of bytes.
Definition: Allwize.cpp:1013
String getMID()
Returns the Manufacturer ID string.
Definition: Allwize.cpp:604
String getUID()
Returns the Unique ID string.
Definition: Allwize.cpp:612
void repeater()
Sets the module in repeater mode.
Definition: Allwize.cpp:124
void master()
Sets the module in master mode.
Definition: Allwize.cpp:104
allwize_message_t read()
Returns latest received message.
Definition: Allwize.cpp:267
void setDecryptFlag(uint8_t flag)
Sets the decrypt flag setting.
Definition: Allwize.cpp:537
int _readBytesUntil(char terminator, char *buffer, uint16_t len)
Reads the stream buffer up to a certain char or times out.
Definition: Allwize.cpp:1033
void dump(Stream &debug)
Dumps the current memory configuration to the given stream.
Definition: Allwize.cpp:158
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:830
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:234
void _bin2hex(uint8_t *bin, char *hex, uint8_t len)
Converts a binary buffer to an hex c-string.
Definition: Allwize.cpp:1066
void getDefaultKey(uint8_t *key)
Gets the default encryption key.
Definition: Allwize.cpp:561
void setControlInformation(uint8_t ci)
Sets the control information byte.
Definition: Allwize.cpp:279
void setTimeout(uint8_t timeout)
Sets the timeout for auto sleep modes.
Definition: Allwize.cpp:419
bool ready()
Test whether the radio module is ready or not.
Definition: Allwize.cpp:146
bool _decode()
Decodes the current RX buffer contents.
Definition: Allwize.cpp:892
int _timedRead()
Reads a byte from the stream with a timeout.
Definition: Allwize.cpp:994
uint8_t getInstallMode()
Gets the install modevalue stored in non-volatile memory.
Definition: Allwize.cpp:513
uint8_t getNetworkRole()
Gets the current network role.
Definition: Allwize.cpp:443
uint8_t getSleepMode()
Gets the sleep mode stored in non-volatile memory.
Definition: Allwize.cpp:377
void setControlField(uint8_t value, bool persist=false)
Sets the data interface for receiving packets.
Definition: Allwize.cpp:486
uint8_t getDataRate()
Gets the data rate stored in non-volatile memory.
Definition: Allwize.cpp:343
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:584
uint8_t getChannel()
Gets the channel stored in non-volatile memory.
Definition: Allwize.cpp:305
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:969
void setPower(uint8_t power, bool persist=false)
Sets the RF power.
Definition: Allwize.cpp:314
uint8_t getLEDControl()
Gets the current LED control.
Definition: Allwize.cpp:459
void setMode(uint8_t mode, bool persist=false)
Sets the module in one of the available MBus modes.
Definition: Allwize.cpp:352
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:945
bool reset()
Resets the radio module. You must reset the serial connection after the reset: Serial1.end(); Serial1.begin(19200); delay(200);.
Definition: Allwize.cpp:56
uint8_t getDevice()
Returns the device version from non-volatile memory.
Definition: Allwize.cpp:628
uint8_t getEncryptFlag()
Gets the encrypt flag setting.
Definition: Allwize.cpp:529
bool send(uint8_t *buffer, uint8_t len)
Sends a byte array.
Definition: Allwize.cpp:211
void begin()
Inits the module communications.
Definition: Allwize.cpp:43
uint8_t getMode()
Gets the MBus mode stored in non-volatile memory.
Definition: Allwize.cpp:361
uint8_t getVersion()
Returns the module version from non-volatile memory.
Definition: Allwize.cpp:620
String getPartNumber()
Returns the module part number.
Definition: Allwize.cpp:636
void setDefaultKey(uint8_t *key)
Sets the default encryption key.
Definition: Allwize.cpp:553
void wakeup()
Wakes up the radio from sleep mode.
Definition: Allwize.cpp:139
void _hex2bin(char *hex, uint8_t *bin, uint8_t len)
Converts a hex c-string to a binary buffer.
Definition: Allwize.cpp:1053
void setPreamble(uint8_t preamble)
Sets the RSSI mode value.
Definition: Allwize.cpp:401
void sleep()
Sets the radio module in sleep mode.
Definition: Allwize.cpp:132
bool _setConfig(bool value)
Sets or unsets config mode.
Definition: Allwize.cpp:677
uint16_t getVoltage()
Returns the internal voltage of the module.
Definition: Allwize.cpp:594
uint8_t getTimeout()
Gets the current timeout for auto sleep modes.
Definition: Allwize.cpp:427
void setNetworkRole(uint8_t role)
Sets the network role.
Definition: Allwize.cpp:435
int8_t _receive()
Listens to incomming data from the module until timeout or END_OF_RESPONSE. Returns the number of byt...
Definition: Allwize.cpp:958
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:813
uint8_t getDecryptFlag()
Gets the decrypt flag setting.
Definition: Allwize.cpp:545
Allwize(Stream &stream, uint8_t reset_gpio=0xFF)
Allwize object constructor.
Definition: Allwize.cpp:33
String getSerialNumber()
Returns the module serial number.
Definition: Allwize.cpp:663
void setLEDControl(uint8_t value)
Sets the LED control.
Definition: Allwize.cpp:451
bool _setMemory(uint8_t address, uint8_t *data, uint8_t len)
Sets non-volatile memory contents starting from given address.
Definition: Allwize.cpp:750
uint8_t getPower()
Gets the RF power stored in non-volatile memory.
Definition: Allwize.cpp:325
uint8_t getControlField()
Gets the control field value stored in non-volatile memory.
Definition: Allwize.cpp:495
String getRequiredHardwareVersion()
Returns the module hardware revision.
Definition: Allwize.cpp:645