You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: README.md
+84-50
Original file line number
Diff line number
Diff line change
@@ -1,13 +1,13 @@
1
1
# SmartCC1101
2
-
This driver library offers a simple access to data transfer using the cc1101 module. It gives access to many configuration options without need to use RFStudio.
2
+
This driver library offers a simple access to data transfer using the **CC1101** module. It gives access to many configuration options without need to use RFStudio.
3
3
## Basic Function
4
4
This library was mainly implemented to efficiently send data from decentral battery powered sensors to a central hub. Howwever it may as well be used for bi-directional communication between several nodes.
5
-
The maximum amount of data which can be be sent in a single transfer is limited to the size of the internal buffer of the CC1101, leading to a possible payload of 61 bytes.
5
+
The maximum amount of data which can be be sent in a single transfer is limited to the size of the internal buffer of the **CC1101**, leading to a possible payload of 61 bytes.
6
6
The code was designed to have a small memory footprint and runs fine on an Arduino Pro Mini (ATMega328p). However, for a single caclulation, floating point math is needed, excluding platforms like ATTiny. In a future version, I might re-implement the offending algortihm to integer math tpo remove the restriction. Besides that, no specific platform-dependant code is used and the library should behave well everywhere else (although it is only explicitely testetd on Arduino Pro Mini and ESP8266).
7
7
## Wiring
8
8
I promise I will add some drawings later on, but for now, I'll stick with the pin numbers - which are standard pins for SPI connections on the boards mentioneed.
9
9
10
-
### CC1101
10
+
### **CC1101**
11
11
If the module lays with the antenna connectors to the top, on the lower connection pins are from left to right:
12
12
+ VCC
13
13
+ GND
@@ -18,7 +18,7 @@ If the module lays with the antenna connectors to the top, on the lower connecti
18
18
+ GDO0 (unused)
19
19
+ CS (or CSN)
20
20
21
-
The modules usually support voltages from 1.8V to 3.6V, so please use a level converter when connecting to a 5V CPU board. Also, be careful when soldering the connections, I have grilled several CC1101 modules...
21
+
The modules usually support voltages from 1.8V to 3.6V, so please use a level converter when connecting to a 5V CPU board. Also, be careful when soldering the connections, I have grilled several **CC1101** modules...
22
22
23
23
### Processor boards
24
24
**Arduino Pro Mini (ATMega328p)**
@@ -59,26 +59,26 @@ The settings are not limited to the `setup()` and may be changed anytime in the
59
59
voidsetup() {
60
60
Serial.begin(115200);
61
61
62
-
Smartcc1101.init(); // must be called first to initialize the CC1101
62
+
SmartCC1101.init(); // must be called first to initialize the **CC1101**
63
63
64
-
if (Smartcc1101.getCC1101()) { // Check the CC1101 SPI connection.
65
-
Serial.println(F("[I] CC1101 connected."));
64
+
if (SmartCC1101.get**CC1101**()) { // Check the **CC1101** SPI connection.
SmartCC1101.setWhiteData(true); // Turn data whitening on / off. false = Whitening off (default). true = Whitening on.
111
+
SmartCC1101.setCRCCheck(true); // true = CRC calculation in TX and CRC check in RX enabled. false = CRC disabled for TX and RX (default).
112
112
}
113
113
114
114
115
115
voidloop() {
116
-
uint8_t buffer[61]{ 0 }; // buffer for the data received by CC1101
116
+
uint8_t buffer[61]{ 0 }; // buffer for the data received by **CC1101**
117
117
118
-
int len = Smartcc1101.receiveData(buffer);
118
+
int len = SmartCC1101.receiveData(buffer);
119
119
// len will be 0 if nothing is yet received.
120
120
if (len > 0) {
121
121
Serial.print(len);
122
122
Serial.println(" bytes received.");
123
123
124
124
// check transfer quality parameters
125
-
int8_t RSSI = Smartcc1101.getRSSI();
126
-
bool CRC = Smartcc1101.checkCRC();
127
-
uint8_t LQI = Smartcc1101.getLQI();
125
+
int8_t RSSI = SmartCC1101.getRSSI();
126
+
bool CRC = SmartCC1101.checkCRC();
127
+
uint8_t LQI = SmartCC1101.getLQI();
128
128
129
129
// will try to interpret the buffer received as character array, just make sure it's zero-terminated.
130
130
// if it was actually sent from a character array, this is not necessary
@@ -151,11 +151,11 @@ void loop() {
151
151
152
152
## Funtion reference
153
153
154
-
`void init(void)` must be called prior to using any other funtion. Will establish the necessary setup of the CC1101 chip. Only exception: `gtCC1101()`.
154
+
`void init(void)` must be called prior to using any other funtion. Will establish the necessary setup of the **CC1101** chip. Only exception: `getCC1101()`.
155
155
156
156
`bool checkCRC(void)` Check if CRC is correct. Only meaningful after data is received via `receiveData()`.
157
157
158
-
`bool getCC1101(void)` checks for the presence of a CC1101 module on the SPI bus.
158
+
`bool getCC1101(void)` checks for the presence of a **CC1101** module on the SPI bus.
159
159
160
160
`uint8_t getLQI(void)` Link Quality Indicator. The Link Quality Indicator is a metric of the current quality of the received signal (smaller is better). When called after data is received via `receiveData()`. LQI corresponds to the data received. If called intermittently, returns the current link quality.
161
161
@@ -177,23 +177,39 @@ void loop() {
177
177
| adc_YES0BC | Address check and 0 (0x00) broadcast |
178
178
| adc_YES0FFBC | Address check and 0 (0x00) and 255 (0xFF) broadcast |
179
179
180
-
`void setCarrierFrequency(uint32_t freq)` Set tranmsision frequency in Hz. Default = 868.35 MHz). The cc1101 can use 300-348 MHZ, 387-464MHZ and 779-928MHZ. More info in the datasheet. Must match sender and receiver.
180
+
`void setCarrierFrequency(uint32_t freq)` Set tranmsision frequency in Hz. Default = 868.35 MHz). The **CC1101** can use the frequenciy ranges 300-348 MHZ, 387-464MHZ and 779-928MHZ.
181
+
> [!WARNING]
182
+
> Please respect local regulations.
183
+
184
+
> [!IMPORTANT]
185
+
> Must match sender and receiver.
186
+
187
+
> [!NOTE]
188
+
> The effective carrier frequencies are quantized, the function will set it to the next possible lower value.
181
189
182
190
`void setCRCCheck(bool crcc)` On TX, enables CRC to be added to the payload. On RX, will calculate the CRC of received data and compare with CRC transmitted. Defaults to `false`.
183
191
184
-
`void setCRC_AF(bool af)` Autoflushes RX buffer if CRC check fails (if `setCRCCheck(true)`). No effect if `setCRCCheck(false)`.
185
-
192
+
`void setCRC_AF(bool af)` Autoflushes RX buffer if CRC check fails (if `setCRCCheck(true)`). Has no effect if `setCRCCheck(false)`.
193
+
186
194
`void setDCFilterOff(bool dcf)` Disable digital DC blocking filter before demodulator. Only for data rates ≤ 250 kBaud. The recommended IF frequency changes when the DC blocking is disabled. true = Disable (current optimized), false = Enable (better sensitivity).
187
195
188
196
`void setDelayFunction(void delayFunc(uint8_t))` The function supplied will be called repeatedly while waiting from the transmission to finish in `sendData()`. It must support a single parameter of type `uint8_t`, which is the delay in ms. If not set, `delay()` will be called. Should be needed only in very special caeses.
189
197
190
-
`void setDeviation(uint32_t deviation)` Set the frequency deviation in Hz. Possible values from 1586 to 380850. Default is 47607 Hz. Note: the algorithm rounds down. Using the exact interval limits, the next lower value might be taken (e.g. for 47607, you must actually specify 4760**8**.
198
+
`void setDeviation(uint32_t deviation)` Set the frequency deviation in Hz. Possible values from 1586 to 380850. Default is 47607 Hz.
199
+
> [!NOTE]
200
+
> the effective deviation values are quantized and algorithm rounds down. Using the exact interval limits, the next lower value might be taken (e.g. for 47607, you must actually specify 4760**8**.
201
+
202
+
`void setFEC(bool fec)` Enable forward error correction. Only supported in fixed packet length mode (`PacketLengthConfig(pktl_FIXED)`) and `setCRCCheck(true)`.
203
+
204
+
`void setManchester(bool menc)` Enable Manchester encoding. Defaults to `false`.
205
+
> [!IMPORTANT]
206
+
> Must match sender and receiver.
191
207
192
-
`void setFEC(bool fec)` Enable forward error correction. Only supported in fixed packet length mode (`PacketLengthConfig(pktl_FIXED)`) and `setCRCCheck(true)`.
193
208
194
-
`void setManchester(bool menc)` Enable Manchester encoding. Defaults to `false`. Must match on sender and receiver.
209
+
`void setModulation(Modulation m)` Set modulation mode. I nearly exclusively use 2FSK modulation.
210
+
> [!IMPORTANT]
211
+
> Must match sender and receiver.
195
212
196
-
`void setModulation(Modulation m)` Set modulation mode. Should match sender and receiver. I nearly exclusively use 2FSK modulation.
197
213
| Value | Modulation |
198
214
|------------|-------|
199
215
|mod_2FSK| 2FSK modulation (default)|
@@ -202,37 +218,47 @@ void loop() {
202
218
|mod_4FSK| 4FSK modulation|
203
219
|mod_MSK| MFSK modulation|
204
220
205
-
`void setLengthConfig(PacketLengthConfig pktl)`From the different options the CC11101 supports in hardware, only the following two options are imlemented in this driver:
221
+
222
+
`void setLengthConfig(PacketLengthConfig pktl)` From the different options the CC11101 supports in hardware, only the following two options are imlemented in this driver:
206
223
| Value | Packet length configuration |
207
224
|------------|-------|
208
225
| pktl_FIXED | fixed packet length as configured by `setLengthConfig()`|
209
226
| pktl_VARIABLE | Variable packet length |
210
227
211
-
`void setPA(int8_t pa)` Set TXPower in dB. The following settings are possible depending on the frequency band: -30, -20, -15, -10, -6, 0, 5, 7, 10, 11, 12. Default is max.
228
+
`void setPA(int8_t pa)` Set TXPower in dB. The following settings are possible depending on the frequency band: -30, -20, -15, -10, -6, 0, 5, 7, 10, 11, 12. Default is max.
229
+
> [!WARNING]
230
+
> Please respect local regulations.
231
+
232
+
> [!NOTE]
233
+
> The effective PA values are quantized, the function will set it to the next possible lower value.
212
234
213
235
`void setPacketLength(uint8_t len)` Packet lentgh when `setLengthConfig(pktl_FIXED)`. On variable packet length, configures maximum packet length (optional). Defaults to 0.
214
236
215
-
`void setPktFormat(PacketFormat pktf)` Although the CC1101 supports different packet formats, only "normal" and RANDOM_TX are supported.
237
+
`void setPktFormat(PacketFormat pktf)` Although the **CC1101** supports different packet formats, only "normal" and RANDOM_TX are supported.
216
238
| Value | Packet format |
217
239
|------------|-------|
218
240
| pktf_NORMAL | Normal mode, use FIFOs for RX and TX (default)|
219
241
| pktf_RANDOMTX | sends random data using PN9 generator. Used for test. Works as normal mode, setting 0 (00) in RX |
220
242
221
243
`void setPRE(preamble_Bytes pre)` When enabling TX, the modulator will start transmitting the preamble. When the programmed number of preamble bytes has been transmitted, the modulator will send the sync word and then data from the TX FIFO.
244
+
> [!IMPORTANT]
245
+
> Must match sender and receiver.
246
+
222
247
| Value | Preamble Bytes |
223
248
|------------|-------|
224
249
| pre_2 |2 preamble bytes |
225
250
| pre_3 | 3 preamble bytes |
226
-
| pre_4 | 4 preamble bytes |
251
+
| pre_4 | 4 preamble bytes (default) |
227
252
| pre_6 | 6 preamble bytes |
228
253
| pre_8 | 8 preamble bytes |
229
254
| pre_12 | 12 preamble bytes |
230
255
| pre_16 | 16 preamble bytes |
231
256
| pre_24 = |/ 24 preamble bytes |
232
257
258
+
233
259
`void setPQT(uint8_t pqt)` The preamble quality estimator increases an internal counter by one each time a bit is received that is different from the previous bit, and decreases the counter by eight each time a bit is received that is the same as the last bit. A threshold of 4∙PQT for this counter is used to gate sync word detection. By setting the value to zero, the preamble quality qualifier of the sync word is disabled. Defaults to 0.
234
260
235
-
`void setRX(void)` Set the CC1101 to RX mode. Repeated calls do not have any effect, unless data was received in the meantime. If the internal buffer is not read via `receiveData()`, the data is lost.
261
+
`void setRX(void)` Set the **CC1101** to RX mode. Repeated calls do not have any effect, unless data was received in the meantime. If the internal buffer is not read via `receiveData()`, the data is lost.
236
262
237
263
`void setRXBandWitdth(rx_BandWidth bw)` Set the Receive Bandwidth. Value can be cosen from predefined list of values:
238
264
| Bandwidth | Value |
@@ -253,24 +279,32 @@ void loop() {
253
279
| 650kHz | bw_650kHz |
254
280
| 812kHz | bw_812kHz |
255
281
256
-
`void setSymbolRate(double symbolRate)` Data transmission rate in baud. Value from 20 to 1621830 Default is 115051 Baud. Must match on sender and receiver.
282
+
`void setSymbolRate(double symbolRate)` Data transmission rate in baud. Value from 20 to 1621830 Default is 115051 Baud.
283
+
> [!IMPORTANT]
284
+
> Must match on sender and receiver.
285
+
286
+
> [!NOTE]
287
+
> The effective symbol rates are quantized, the function will set it to the next possible lower value.
`void setSyncMode(sync_Mode syncm)` Combined sync-word qualifier mode. The hardware supports carrier sense with abolute and relative thresholds as well, but this is not implemented.
290
+
>[!IMPORTANT]
291
+
> `sync_3032` enables duplicate transmission of the sync word in TX. This must match the setting in RX, so chose `sync_3032` here as well.
292
+
259
293
| Value | Sync-Mode |
260
294
|------------|-------|
261
295
| sync_NONE | No preamble/sync |
262
296
| sync_1516 | 15/16 sync word bits detected |
263
297
| sync_1616 | 16/16 sync word bits detected (default)|
264
298
| sync_3032 | 30/32 sync word bits detected |
265
-
| sync_NONECS | No preamble/sync, carrier-sense above threshold |
`void setSyncWord(uint8_t sh, uint8_t sl)` If sync-word detection is enabled via setSyncMode,the CC1101 will not start filling the RX FIFO unless a valid sync word is detected.
300
+
`void setSyncWord(uint8_t sh, uint8_t sl)` If sync-word detection is enabled via setSyncMode,the **CC1101** will not start filling the RX FIFO unless a valid sync word is detected.
301
+
> [!IMPORTANT]
302
+
> Must match on sender and receiver.
271
303
272
-
`void setWhiteData(bool white)` Enable data whitening. Defaults to `false`. Must match on sender and receiver.
304
+
`void setWhiteData(bool white)` Enable data whitening. Defaults to `false`.
305
+
> [!IMPORTANT]
306
+
> Must match on sender and receiver.
273
307
274
-
`void sleep(void)` Sets the CC1101 to sleep mode, reducing power consumption. The next access will wake the chip up again, no special procedure is needed.
308
+
`void sleep(void)` Sets the **CC1101** to sleep mode, reducing power consumption. The next access will wake the chip up again, no special procedure is needed.
0 commit comments