-
Notifications
You must be signed in to change notification settings - Fork 1
/
guide
315 lines (250 loc) · 16.7 KB
/
guide
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
Function Descriptions
Last Modified - May 9, 2017
Note: Work in Progress!!!
Intro: Below is a list of the module functions so far that I've developed.
Most of the functions are for setting the various parameters for the radio,
2 for transmit and receive, 1 to get the last RSSI value and 1 to get the
temperature via the radios temperature sensor.
transmit(transmitData, addressOn=False, toAddress=0,fromAddress=None,
ack=False, ackPattern=0, packetLength=64)
– function to transmit data from the radio. Transmits a single packet of data
- transmitData: data to be transmitted, should be in string format. Data larger
than the packetLength will be truncated to fit the packetLength.
- addressOn: if true an address byte will be added to the data to be sent
- toAddress: the address byte to be sent if any address is being sent
- fromAddress: if non-zero value, adds a byte of data of the radio senders address,
adds the byte one byte before ackPattern
- ack: if true will add the ackPattern data immediately before the data to be sent
- ackPattern: optional acknowledge pattern to be added to packet sent
- packetLength: length of packet radio is expecting to send, if fixed length
mode is used this should match the payload length parameter the radio is using
transmit_with_ack(txData, toAddress=0,intType = 'hw',retry=0, packetLength=64)
- function to transmit data with acknowledge back from the receiver after each
packet sent Can transmit multiple packets.
- txData: list of data to be sent, each list entry should either be in string or
bytearray format
- toAddress: the address byte to be sent if any address is being sent
- intType: interrupt type to be used, either 'hw' or 'sw' (hardware or software).
For hardware interrupts the radios interrupt pin has to be set and the pi GPIO
used has to be set using the set_dio(dio0=1) and set_interrupt_pin([PiGPIO#])
functions respectively.
- retry: - max number of times to resend a packet to try to get a successful
acknowledge back from the receving radio
- packetLength: length of packet radio is expecting to send, if fixed length
mode is used this should match the payload length parameter the radio is using
Function returns 2 values, one for # of successfully sent packages (i.e. an acknowledge
received within the max retries allowed per packet) and one for failed sent packages
(i.e. no acknowledge received within the max retries allowed per packet)
receive(timeout=999, background=False) – function to receive data sent to the radio
- timeout: length of time the radio should stay in receive mode, a value of -1
will leave the radio in receive mode indefinately. To cancel the radio out of
receive mode early set the radio objects receiveTimeout variable to 0.
- background – a value of False will leave the receive function inline with your
program, i.e. you program won't progress past the receive function until the
timeout length is reached. A value of True will put the receive function into
the background via a seperate thread so your program can proceed past the receive
function and do other stuff while the gathing receive data.
All received data is put into the radio object's receiveData[] list.
receive_hw_int() - function to receive data sent to the radio using a hardware interrupt
to monitor for incoming packets.
- for hardware interrupts the radios interrupt pin has to be set and the pi GPIO used
has to be set using the set_dio(dio0=1) and set_interrupt_pin([PiGPIO#]) functions
respectively.
- the length of time the receiver is on for is set by the receive_timeout() function.
A value of -1 will leave the radio in receive mode indefinately. A value of 0 (zero)
will cancel the radio out of receive mode immediately. The receive_timeout() function
takes a value in seconds (s)
All received data is put into the radio object's receiveData[] list.
receive_sw_int() - function to receive data sent to the radio using a software interrupt
to monitor for incoming packets.
- the length of time the receiver is on for is set by the receive_timeout() function.
A value of -1 will leave the radio in receive mode indefinately. A value of 0 (zero)
will cancel the radio out of receive mode immediately. The receive_timeout() function
takes a value in seconds (s)
All received data is put into the radio object's receiveData[] list.
receive_timeout(time=0) – this function sets the amount of time the radio is in receive mode
- time: Value in seconds (s). A value of -1 will leave the radio in receive mode indefinately.
A value of 0 (zero) will cancel the radio out of receive mode immediately.
- sets self.receiveTimeout variable
last_rssi() - this function returns the last received signal strength indicator
stored in the radio's rssi register (RegRssiValue) - this will be an integer
value in dBm
temperature() - this function will return the temperature obtained from the
radio's temperature sensor – this will be an integer value. Note: the
temperature sensor will likely need to be calibrated against a know temperature.
The radio object has a temperatureOffset variable that will need to be set.
This can be done with the set_temperature_offset() function.
Radio Set up Functions
set_acks(receiveAck=0, sendAck=0) – function to set the receive and send ACK patterns used
by the radio. Patterns should be a single byte long.
- receiveAck: pattern send by the transmitter asking for an acknowledgement back and looked
for by the receiver to trigger sending an acknowledgement
- sendAck: pattern sent by the receiver back to the transmitter in response to a receiveAck.
Pattern looked for by the transmitter indicating a succesful packet sent.
- sets self.sendAck and self.receiveAck variables
set_address_filtering(mode='none')– function to set the addressing filtering mode
- mode: valid string values; none, node or both. None means no address filtering is used, node requires
address matching to the node address and both requires either node address or broadcast address matching
- sets bits 1&2 of RegPacketConfig1 (0x37)
set_afc(afcLowBetaOn='Standard', afcOffset=0, dccFreq=4, rxBW=10.4, autoclearOn='off', autoOn='on')– function
to set the parameters for automatic frequency correction.
- afcLowBetaOn -valid values are 'Standard' or 'Improved' and sets bit 5 of RegAfcCtrl (0x0B)
- afcOffset – sets afc offset in low beta systems (i.e. afcLowBetaOn = Improved), pass an integer value in Hz.
Sets RegTestAfc (0x71)
- dccFreq – valid values are 0.125, 0.25, 0.5, 1, 2, 4, 8, 16
- rxBW – valid values are 2.6, 3.1, 3.9, 5.2, 6.3, 7.8, 10.4, 12.5, 15.6, 20.8, 25, 31.3, 41.7, 50.0, 62.5,
83.3, 100.0, 125.0, 166.7, 200.0, 250.0, 333.3, 400.0, 500.0. Together with dccFreq sets RegAfcBw (0x1A)
- autoclearOn – valid values are 'on' and 'off'
- autoOn – valid values are 'on' and off. Together with autoclearOn sets bits 2 & 3 of RegAfcFei (0x1E)
set_auto_rx_restart(autoRestartOn='on', interPacketDelay=0x0) - function to enable/disable the automatic
Rx restart (RSSI phase) feature of the radio and set the InterPacketRxDelay
- autoRestartOn – valid values are 'on' and 'off'
- interPacketDelay – pass an integer between 0 and 15
- sets bits 1 & 4-7 of RegPacketConfig2 (0x3D)
set_bitrate(bitrate) – function to set the radio transmission bitrate
- bitrate – pass an integer value in bits per seconds
- sets registers RegBitrateMsb & RegBitrateLsb (0x03 & 0x04)
set_broadcast_address(address=0x07)– function to set the broadcast address used in address filtering
- address – pass an integer between 1 and 255 in decimal or hex
- have had issues with even numbered address
- sets register RegBroadcastAdrs (0x3A)
set_checksum(crcOn='on', autoClearFifo='0n') – function to set the radio's checksum calculation function
- crcOn – value is either 'on' or 'off', if 'on' a 2 byte checksum value is added to the transmitted data
and the checksum calculation is performed on received data.
- autoClearFifo – value is either 'on' or 'off', if 'on' and crcOn is 'on', if the checksum fails the
payload ready interrupt will not occur and the fifo will be cleared
- sets bits 3 & 4 of RegPacketConfig1 (0x37)
set_data_mode(dataMode='packet', modulationType='FSK', modShaping='none', bitSynchOn='on') – function to set
the data mode parameters
- dataMode – valid choices are 'continuous' and 'packet'
- modulationType – valid choices are 'FSK' or 'OOK'
- modShaping – for modulationType of 'OOK', valid values are 0, 1 , 2 with 0 meaing no shaping. For
modulationType of 'FSK', valid values are 0, 1, 0.5, 0.3 with 0 again meaning no shaping.
- bitSynchOn – valid values are 'on' or 'off'. This only applies with dataMode of 'continuous' and
will set the dataMode with or without the bit synchronizer on.
- sets RegDataModul (0x02)
set_dc_free_encoding(encodingType='none') – function to enable/disable DC free encoding,
- encodingType – 3 choices 'none', 'manchester' or 'whitening'
- sets bits 5 & 6 of RegPacketConfig1 (0x37)
set_dio(dio0=0, dio1=0, dio2=0, dio3=0, dio4=0, dio5=0, clkOut='off') - function to map the DIO (digital I/O)
pins of the radio as well as set the clock output frequency if used
- dio0 – dio5 – pass an integer between 0 and 3 for each dio
- clkOut – valid values are 'off', 'auto', 1, 2, 4, 8, 16 and 32
- sets RegDioMapping1 (0x25) and RegDioMapping2 (0x26)
set_encryption(aesOn='on', aesKeyList=[]) - function to enable/disable AES encryption and set the 16 AES
encyption key registers. If aesKeyList is left empty the AES key registers will be left as is
- aesOn – valid values are 'on' and 'off'
- aesKeyList – pass a list of 16 integers (decimal or hex) with values between 1 and 255.
- sets bit 0 of RegPacketConfig2 (0x3D) and RegAesKey1 – RegAesKey16 (0x3E - 0x4D)
set_fifo_threshold(txStartCond='FifoLevel', threshold=20) - function to define the condition to start packet
transmission and set the Fifo threshold used to trigger the FifoLevel interrupt
- txStartCond – valid values are 'FifoLevel' and 'FifoNotEmpty'
- threshold – pass an integer value between 0 and 66
- sets RegFifoThresh (0x3C)
set_frequency(frequency) – function to set the tranceiver's tx/rx frequency
- frequency – pass an integer value in Hz
- sets registers RegFrfMsb, RegFrfMid & Reg FrfLsb (0x07-0x09)
set_frequency_deviation(fDev) - function to change the radio transmission frequency deviation
- fDev – pass an integer value in Hz
- sets registers RegFdevMsb & RegFdevLsb (0x05 & 0x06)
set_interrupt_pin(intPin=0) – function to tell the radio module which of the Pi's GPIO pins is being
used to receive the hardware (hw) interrupt signal from the radio
- intPin: Pi GPIO pin number
- sets self.intPin variable
set_lna(autoOn='on', gainSelect='G1', inputZ=50) - function to set the parameters for the receiver's
LNA (low noise amplifier)
- autoOn – valid values are 'on' and 'off''. Set to 'on' the LNA gain is set automatically by the
radio's internal AGC loop, otherwise the gain is set manually by the user.
- gainSelect – valid values are 'G1', 'G2', 'G3', 'G4', 'G5', 'G6'. This will manually set the LNA
gain level if autoOn is set to 'off'
- inputZ – valid values are 50 or 200 (ohms) and sets the LNA's input impedance
- sets RegLna (0x18)
set_mode_sequencer(sequencer='on') - function to enable/disable the radio's automatic sequencer
- sequencer – valid values are 'on' and 'off'
- sets bit 7 of RegOpMode (0x01)
set_node_address(address=0x05)- function to set the node address used in address filtering
- address – pass an integer between 1 and 255 in decimal or hex
- have had issues with even numbered addresses
- sets register RegNodeAdrs (0x39)
set_OCP(ocpOn='on', ocpMax=95) - function to enable/disable OCP (Over Current Protection) and set the
max current (mA)
- ocpOn - valid values are 'on' and 'off'
- ocpMax – pass an integer value between 45 and 120 (mA)
- sets register RegOcp (0x13)
set_operating_mode(mode='standby') - function to set the radio's current mode
- mode – valid values are 'transmit', 'receive', 'sleep', 'freqSynth' and 'standby'
- sets bits 2-4 of RegOpMode (0x01)
set_packet_format(packetFormat='fixed',payloadLength=64) - function to set the packet format including
fixed vs variable vs unlimited length and payload length
- packetFormat – valid values are 'variable', 'fixed' and 'unlimited'
- payloadLength – pass an integer between 1 and 255
- sets bit 7 of RegPacketConfig1 (0x37) and all of RegPayloadLength (0x38)
- sets self.packetFormat variable
set_power(ampSelect, powerLevel, powerRamp=40) - function to choose the power amplifier(s), transmit
power used and power ramp time
- ampSelect – valid values are 'Pa0', 'Pa1', 'Pa2' and 'Pa2H'. Pa2H is for high power PA setting,
registers RegTestPa1, RegTestPa2 and RegTestAfc should also be altered accordingly. These functions
are not yet developed but the set_register_by_address or set_register_by_name function could be used.
- powerLevel – pass an integer value between -18 and 13 for Pa0, between -2 and 13 for Pa1, between
2 and 17 for Pa2 and between 5 and 20 for Pa2H.
- powerRamp – valid values are (micro seconds); 10, 12, 15, 20, 25, 31, 40, 50, 62, 100, 125, 250,
500, 1000, 2000 and 3400
- sets RegPaLevel (0x11) and RegPaRamp (0x12)
set_preamble_length(length=2) - function to set the length of the preamble (bytes)
- length – pass an integer value between 1 and 65535
- sets RegPreambleMsb (0x2C) and RegPreamble (0x2D)
set_register_by_address(registerAddr, value) - function to set a single register by passing the
register address and the value for it to be set to. The radio object registerList is also updated
- registerAddr – register address ( i.e. 0x2C)
- value – pass the value you want to set the register to
set_register_by_name(registerName, value) - function to set a single register by passing the register
name and the value for it to be set to. The radio object registerList is also updated
- registerName – name of the register to set, the naming convention from the radio datasheets
are used (i.e. RegPreambleMsB)
- value – pass the value you want to set the register to
set_rssi_threshold(rssi) - funstion to change the receive signal strength indicator (rssi) threshold
(dBm) used by the receiver
- rssi – pass an float value (dBm) between 0 and 127.5
- sets RegRssiThresh (0x29)
set_rxbw(dccFreq=4, rxBW=10.4) - function to set the receiver bandwidth parameters when afc
(automatic frequency correction) is not enabled
- dccFreq – valid values are 0.125, 0.25, 0.5, 1, 2, 4, 8, 16
- rxBW – valid values are 2.6, 3.1, 3.9, 5.2, 6.3, 7.8, 10.4, 12.5, 15.6, 20.8, 25, 31.3, 41.7,
50.0, 62.5, 83.3, 100.0, 125.0, 166.7, 200.0, 250.0, 333.3, 400.0, 500.0
- sets RegRxBw (0x19)
set_sync(syncOn='on', syncSize=3, syncTol=2, fifoFill=0) - function to set the sync word options
- syncOn – valid values are 'on' and 'off'. Turns sync word generation and detection on or off
- syncSize – pass an integer value (bytes) between 1 and 7. Sets the size of the sync word
- syncTol - pass an integer value (bits) between 1 and 7. Sets the number of tolerated bit errors
in the sync word
- fifoFill – valid values are 0 and 1.
- sets RegSyncConfig (0x2E)
set_sync_word(syncValueList=[0xE2,0x4A,0x26]) - function to set the sync word. This will set the
8 RegSyncValue registers
- syncValueList – pass a list of 1 to 8 integers (decimal or hex). Each integer should be between
1 and 255
- sets registers RegSyncValue1 to RegSyncValue8 (0x2F - 0x36)
set_temperature_offset(offset=0) - function to change the temperature offset value, used to calibrate
the radio temperature sensor reading.
- offset – pass an integer value
set_timeout_rssi_threshold(timeoutOn='off', multiplier=0x00) - function enable/disable the TimeoutRssiThresh
interrupt and to set it's level if enabled
- timeoutOn – valid values are 'on' and 'off'
- multiplier – pass an integer value between 1 and 255
- sets RegRxTimeout2 (0x2B)
set_timeout_rx_start(timeoutOn='off', multiplier=0x00) - function enable/disable the TimeoutRxStart interrupt
and to set it's level if enabled
- timeoutOn – valid values are 'on' and 'off'
- multiplier – pass an integer value between 1 and 255
- sets RegRxTimeout1 (0x2A)
Sent Packet Format
Each packet sent, is sent in the following format. The length, toAddress, fromAddress and Ack bytes are all
optional and only included if selected via the various options. For example the length byte is not included
if using fixed length format packets
Length Byte, toAddress Byte, fromAddress byte, ACK byte, data/payload bytes
Functions that rely on RPi.GPIO module
The following functions rely on the RPi.GPIO module, these are for the hardware interrupts. If you want to
use only the software interrupts or a difffernt GPIO manipulating modules these are the functions that
will need to be modified or deleted.
- receive_ack()
- receive_hw_int()