HCRM95 Library For RM96 LoRa Modules

[admin]

Arduino library for RM95 & RM96 wireless LoRa(TM) modules. This library currently supports the following product(s):

RM95 LoRa 868MHz Band Wireless Module (HCMODU0247)
https://hobbycomponents.com/lora/1188-r ... ess-module


Using the library


Step 1) Downloading the library

Download the latest HCRM95 library from the download section found at the bottom of this post.

Save it to somewhere convenient on your computer.



Step 2) Installing the Library

Once downloaded, open up your Arduino IDE and go to Sketch->Include Library->Add .ZIP Library.

In the file selection dialogue window that opens up, navigate to wherever you downloaded the HCRM95_Vx_x.zip file and select it, then click the ‘Open’ button.

Alternatively you can just unzip the library into your Arduino library folder usually found in the following location:


On Windows:
My Documents\Arduino\libraries\

On Mac:
Documents/Arduino/libraries/

Linux:
Usually found within the users home area under /Arduino/libraries/



Step 3) Including the library in your sketch

Adding the library to your sketch consists of 3 steps; Firstly, include the HCRM95 header file (HCRM95.h) at the top of your sketch, create an instance of the library, then finally initialise the library inside the startup() function:

Code: [Select all] [Expand/Collapse]

1. // Step 1: Include the mLink library
2. #include "HCRM95.h"
3.  
4.  
5. //Step 2: Create an instance of the library
6. HCRM95 HCRM95;
7.  
8. #define SS_PIN 10                     // Slave select pin (NSS)
9. #define RST_PIN 9                     // Reset pin (RESET)
10.  
11.  
12. void setup()
13. {
14.   // Step 3: Initialise the library  
15.   HCRM95.init(RST_PIN, SS_PIN);
16. }
17.  
18.  
19. void loop()
20. {
21. }

GeSHi © Codebox Plus Extension

HCRM95.init(ssPin, rstPin);

Initialises the library where:

ssPin specifies the Arduino pin number connected to the modules slave select pin.

rstPin specifies the Arduino pin number connected to the modules reset pin.


Returns: void



HCRM95.reset(void);

Resets the RM95

Returns:
Void



HCRM95.cad(void);

Preforms a Channel Activity Detect (CAD). This function can be used to determine if the current channel is clear before performing a transmit.

Returns:
A boolean value where:
0 = No activity
1 = Channel is currently in use



HCRM95.txSend(*data);

Transmits on or more bytes of data where:

*data is a pointer pointing to the start of the data.

Returns:
void

Notes:
See library sketches for examples of how to pass values and text to this function.

This is a non-blocking function and will exit before the module has finished transmitting. You can use the txDone() function to determine if the module has finished transmitting before using the above function again.



HCRM95.txDone(void);

Checks to see if the module is currently transmitting.

Returns:
A boolean value where:
false = not transmitting
true = transmitting



HCRM95.rxAvailable(void);

Checks to see if any data has been received.

Returns:
A boolean value where:
false = no new data
true = new data available



HCRM95.getRx(*data);

Reads the last received data from the FIFO buffer where:

*data is a pointer pointing to the start of memory where the received data will be stored to

Returns:
A byte value containing the number of bytes received.

Notes:
If the size of the received data is greater than the size of the memory area then the data will be cropped.

See library sketches for examples of how to use this function.



HCRM95.rxSize(void);

Returns the size of the received data.

Returns:
A byte value containing the size of the data in bytes



HCRM95.setFreq(freq);

Sets the modules Tx/Rx frequency where:
freq is the required frequency in MHz

Returns:
Void

Notes:
When the library is initialised the default frequency is set to 868MHz (freq = 868).

Please check the correct frequencies of your country before setting this value.



HCRM95.mode(mode);

Sets the operating mode of the module where:
mode is the required mode. Valid values for mode are
MODE_SLEEP low power sleep mode
MODE_STDBY standby mode
MODE_TRANSMIT transmit mode
MODE_RXCONTINUOUS continuous receive mode
MODE_RXSINGLE single receive mode

Returns:
Void

Notes:
When the library is initialised the default frequency operating mode is MODE_SLEEP



HCRM95.setBW(bw);

Sets the RF bandwidth where:
bw is the required bandwidth. Valid values are
BW_7_8KHz
BW_10_4KHz
BW_15_6KHz
BW_20_8KHz
BW_31_25KHz
BW_41_7KHz
BW_62_5KHz
BW_125KHz
BW_250KHz
BW_500KHz

Returns:
Void

Notes:
Lower bandwidth values will reduce the data rate but will increase range.

When the library is initialised the default bandwidth is BW_125KHz



HCRM95.setSF(sf);

Sets the RF spreading factor where:
sf is the required spreading factor. Valid values are
SF_64
SF_128
SF_256
SF_512
SF_1024
SF_2048
SF_4096

Returns:
Void

Notes:
Lower spreading factor values values will reduce the data rate but will increase range.

When the library is initialised the default spreading factor is SF_128



HCRM95.lastRSSI(void);

Gets the RSSI of the last received data.

Returns:
An unsigned int containing the RSSI level in dBm

Value Send Example

Sends an incrementing number to the receiver:
This sketch, together with the receive value example will send and receive an incrementing int variable. It demonstrates how to send and receive a single value such as a sensor reading.

Code: [Select all] [Expand/Collapse]

1. #include "HCRM95.h"
2.  
3. #define SS_PIN 10                     // Slave select pin (NSS)
4. #define RST_PIN 9                     // Reset pin (RESET)
5.  
6.  
7. HCRM95 HCRM95;                        // Create an instance of the library
8.  
9. int counter = 0;                      // Create an int variable to send
10.  
11. void setup()
12. {
13.   HCRM95.init(SS_PIN, RST_PIN);       // Init the library
14. }
15.  
16.  
17.  
18. void loop()
19. {
20.   HCRM95.txSend(counter);             // Send the value
21.  
22.   while(!HCRM95.txDone());            // Wait until the module has finished sending
23.  
24.   counter++;                          // Inc the counter to send a different number next time
25.  
26.   delay(2000);                        // Wait a little before sending again
27. }

GeSHi © Codebox Plus Extension

Receive value example

Receives an incrementing number from the transmitter
This sketch, together with the transmit value example will send and receive an incrementing int variable. It demonstrates how to send and receive a single value such as a sensor reading.

Code: [Select all] [Expand/Collapse]

1. #include "HCRM95.h"
2.  
3. #define SS_PIN 10                     // Slave select pin (NSS)
4. #define RST_PIN 9                     // Reset pin (RESET)
5.  
6.  
7. HCRM95 HCRM95;                        // Create an instance of the library
8.  
9. void setup()
10. {
11.   Serial.begin(9600);
12.  
13.   HCRM95.init(SS_PIN, RST_PIN);       // Init the library
14.  
15.   HCRM95.mode(MODE_RXCONTINUOUS);     // Put module into continuous RX mode
16. }
17.  
18.  
19.  
20. void loop()
21. {
22.   int counter;                        // Create an int variable to store the result
23.  
24.   while(!HCRM95.rxAvailable());       // Wait for new data
25.  
26.   HCRM95.getRx(counter);              // Get the new data
27.  
28.   Serial.println(counter);            // Print it out
29. }

GeSHi © Codebox Plus Extension

Send text example

Sends an example string of text to the receiver:
This sketch, together with the send text receive example will send and receive a char array containing some text.

Code: [Select all] [Expand/Collapse]

1. #include "HCRM95.h"
2.  
3. #define SS_PIN 10                     // Slave select pin (NSS)
4. #define RST_PIN 9                     // Reset pin (RESET)
5.  
6.  
7. HCRM95 HCRM95;                        // Create an instance of the library
8.  
9. void setup()
10. {
11.   HCRM95.init(SS_PIN, RST_PIN);       // Init the library
12. }
13.  
14.  
15. void loop()
16. {
17.   char data[] = "Hello!";             // Create a char array containing some text
18.  
19.   while(HCRM95.CAD());
20.  
21.   HCRM95.txSend(data);                // Send the text
22.  
23.   while(!HCRM95.txDone());            // Wait until the module has finished sending            
24.  
25.   delay(2000);                        // Wait a little before sending again
26. }
27.  

GeSHi © Codebox Plus Extension

Receive text example

Receives a string of text send by the transmitter:
This sketch, together with the send text example will send and receive a char array containing some text.

Code: [Select all] [Expand/Collapse]

1. #include "HCRM95.h"
2.  
3. #define SS_PIN 10                     // Slave select pin (NSS)
4. #define RST_PIN 9                     // Reset pin (RESET)
5.  
6.  
7. HCRM95 HCRM95;                        // Create an instance of the library
8.  
9. void setup()
10. {
11.   Serial.begin(9600);
12.  
13.   HCRM95.init(SS_PIN, RST_PIN);       // Init the library
14.  
15.   HCRM95.mode(MODE_RXCONTINUOUS);     // Put module into continuous RX mode
16. }
17.  
18.  
19.  
20. void loop()
21. {
22.   char data[10];                      // Create a char array big enough to hold the received text
23.  
24.   while(!HCRM95.rxAvailable());       // Wait for new data
25.  
26.   HCRM95.getRx(data);                 // Get the new data
27.  
28.   Serial.println(data);               // Print it out
29. }

GeSHi © Codebox Plus Extension

HCRM95_V1_0_0.zip

Diagrams, libraries, and example code are provided as an additional free service by Hobby Components and are not sold as part of this product. We do no provide any guarantees or warranties as to their accuracy or fitness for purpose.

Descriptions and diagrams on this page are copyright Hobby Components Ltd and may not be reproduced without permission.