HCWireless Arduino Library for 433MHz Wireless Tx & Rx modules

Useful guides, libraries, and example sketches to support our Arduino based products.
admin
Site Admin
Posts: 865
Joined: Sun Aug 05, 2012 4:02 pm

HCWireless Arduino Library for 433MHz Wireless Tx & Rx modules

Post by admin » Fri Jun 21, 2019 1:18 pm

Image




This Arduino compatible library allows for simple interfacing to wireless transmitter/receiver modules.


Currently supported Arduino boards:

All ATMega328 baed Arduino development board - Uno, Nano, Pro Mini etc


Currently supported products.

433MHz wireless transmitter MX-FS-03V & receiver modules MX-05 available via our store
https://hobbycomponents.com/wired-wirel ... -03v-mx-05


This library is provided free to support the open source community. We spend most of our time creating free content like this because we genuinely want to support the open source community. PLEASE SUPPORT US so that we can continue to create free content by purchasing products from our store - HOBBYCOMPONENTS.COM



You will need to download (please log in to download the library) and unzip this library to the Arduino development environments library area.

On Windows:
My Documents\Arduino\libraries\

On Mac:
Documents/Arduino/libraries/

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




Using the HCWireless library


To use the library just include the HCWireless.h header file and then create an instance of the library. E.g:
  1. #include "HCWireless.h"
  2. HCWireless HCWireless;


Before using the library it must first be initialised. To initialise the Tx part of the library (for transmitting data) place the following line in the Setup() loop at the top of the sketch:

  1. HCWireless.txInit(txPin);

Where:

txPin is the digital pin used to connect to the Tx input of the transmitter module.



To initialise the Rx part of the library (for receiving data) place the following line in the Setup() loop at the top of the sketch:
  1. HCWireless.rxInit(rxPin, rxBufferSize);

Where:

rxPin is the digital pin used to connect to the Tx output of the receiver module.

rxBufferSize is the size of the rx buffer in bytes. This must be equal or greater than the amount of data expected to be received in one transmission otherwise a buffer overrun error will be generated and the received data will rejected.


Returns:

A boolean true or false where true = memory allocation for Rx buffer was successful
false = not enough memory for Rx buffer






HCWireless library functions:


  1. byte HCWireless.send(payload);
Transmits the contents of a variable, array or structure as one continuous payload where:

payload is the variable, array, or structure to transmit.


Returns: void

Notes: Size of variable, array, or structure in bytes must not exceed the libraries
maximum Rx buffer size set by the HCWireless.rxInit() library function.

If data is currently being received this function will wait until reception
has completed before transmitting the data.

Whilst transmitting global interrupts are disabled.




  1. byte HCWireless.sendBytes(payload, payloadsize);
Transmits the contents of a variable, array or structure as one continuous payload where:

payload is the variable, array, or structure to transmit.

payloadsize in the size of the array or structure in bytes.


Returns: void

Notes: Size of variable, array, or structure in bytes must not exceed the libraries
maximum Rx buffer size set by the HCWireless.rxInit() library function.

If data is currently being received this function will wait until reception
has completed before transmitting the data.

Whilst transmitting global interrupts are disabled.




  1. byte HCWireless.available();
Gets the amount of data received

Returns: The amount of received data in bytes in the Rx buffer.




  1. byte HCWireless.read(payload);
Reads one or more bytes of data out of the Rx buffer into a variable, array or structure where:

payload is the variable, array, or structure to transfer the data in the Rx buffer into.


Returns: The status as a boolean value where TRUE = transfer successful, FALSE = transfer failed.

Notes: If there are insufficient bytes available in the Rx buffer the function will abort the
transfer and the Rx buffer will be cleared.




  1. byte HCWireless.readBytes(payload, payloadsize);
Reads multiple bytes of data out of the Rx buffer into a variable, array or structure where:

payload is the variable, array, or structure to transfer the data in the Rx buffer into.

payloadsize is the amount of data in bytes to transfer.


Returns: The status as a boolean value where TRUE = transfer successful, FALSE = transfer failed.

Notes: If there are insufficient bytes available in the Rx buffer the function will abort the
transfer and the Rx buffer will be cleared.




  1. byte HCWireless.state();
Gets the error status of the last received data

Returns: The error status as a byte value where 0 = no error.
A value other than zero means an error occurred.
To get the type of error you can logically and the returned value
with one of the following bit masks:

RX_BIT_ERROR // Bit error
RX_EOB_ERROR // End of byte error
RX_EOT_ERROR // End of transmission error
RX_OVR_ERROR // Buffer overflow error
RX_CRC_ERROR // CRC error



  1. [size=150][b]Example Tx Sketch:[/b][/size]
  2.  
  3.  
  4. /* FILE:    HCWireless_Blink_Tx_Example.ino
  5.    DATE:    19/06/19
  6.    VERSION: 1.0
  7.    AUTHOR:  Andrew Davies
  8.    
  9. 19/06/19 version 1.0: Original version
  10.  
  11. This sketch demonstrates how to use the HCWireless library to remotely control the
  12. state of an LED connected to the Arduino at the receiving end. This sketch should be used
  13. in conjunction with the HCWireless_Blink_Rx_Example at the receiving end.
  14.  
  15. Currently this sketch supports the following products:
  16.  
  17. 433MHz wireless transmitter MX-FS-03V & receiver modules MX-05 available via our store
  18. https://hobbycomponents.com/wired-wireless/168-433mhz-wireless-modules-mx-fs-03v-mx-05
  19.  
  20.  
  21. This library is provided free to support the open source community.
  22. We spend most of our time creating free content like this because we genuinely
  23. want to support the open source community. PLEASE SUPPORT US so that we can
  24. continue to create free content by purchasing products from our store -
  25. HOBBYCOMPONENTS.COM
  26.  
  27.  
  28. You may copy, alter and reuse this code in any way you like, but please leave
  29. reference to HobbyComponents.com in your comments if you redistribute this code.
  30. This software may not be used directly for the purpose of selling products that
  31. directly compete with Hobby Components Ltd's own range of products.
  32. THIS SOFTWARE IS PROVIDED "AS IS". HOBBY COMPONENTS MAKES NO WARRANTIES, WHETHER
  33. EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF
  34. MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ACCURACY OR LACK OF NEGLIGENCE.
  35. HOBBY COMPONENTS SHALL NOT, IN ANY CIRCUMSTANCES, BE LIABLE FOR ANY DAMAGES,
  36. INCLUDING, BUT NOT LIMITED TO, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES FOR ANY
  37. REASON WHATSOEVER.
  38. */
  39.  
  40. #include "HCWireless.h"
  41.  
  42. // Digital pin used to connect to the Tx modules data input pin
  43. #define TX_PIN 8
  44.  
  45. // Create an instance of the library
  46. HCWireless HCWireless;
  47.  
  48. boolean ledState = false;
  49.  
  50. void setup()
  51. {
  52.   // Initialise the Tx part of the library
  53.   HCWireless.txInit(TX_PIN);
  54. }
  55.  
  56.  
  57. void loop()
  58. {
  59.   // Send the current state of the LED
  60.   HCWireless.send(ledState);
  61.  
  62.   // Toggle to LED state and wait 1 second before sending the new state
  63.   ledState = !ledState;
  64.   delay(1000);
  65. }



Example Rx Sketch:

  1. /* FILE:    HCWireless_Blink_Rx_Example.ino
  2.    DATE:    19/06/19
  3.    VERSION: 1.0
  4.    AUTHOR:  Andrew Davies
  5.    
  6. 19/06/19 version 1.0: Original version
  7.  
  8. This sketch demonstrates how to use the HCWireless library to remotely control the
  9. state of an LED connected to the Arduino at the receiving end. This sketch should be used
  10. in conjunction with the HCWireless_Blink_Tx_Example at the transmitting end.
  11.  
  12. Currently this sketch supports the following products:
  13.  
  14. 433MHz wireless transmitter MX-FS-03V & receiver modules MX-05 available via our store
  15. https://hobbycomponents.com/wired-wireless/168-433mhz-wireless-modules-mx-fs-03v-mx-05
  16.  
  17.  
  18. This library is provided free to support the open source community.
  19. We spend most of our time creating free content like this because we genuinely
  20. want to support the open source community. PLEASE SUPPORT US so that we can
  21. continue to create free content by purchasing products from our store -
  22. HOBBYCOMPONENTS.COM
  23.  
  24.  
  25. You may copy, alter and reuse this code in any way you like, but please leave
  26. reference to HobbyComponents.com in your comments if you redistribute this code.
  27. This software may not be used directly for the purpose of selling products that
  28. directly compete with Hobby Components Ltd's own range of products.
  29. THIS SOFTWARE IS PROVIDED "AS IS". HOBBY COMPONENTS MAKES NO WARRANTIES, WHETHER
  30. EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF
  31. MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ACCURACY OR LACK OF NEGLIGENCE.
  32. HOBBY COMPONENTS SHALL NOT, IN ANY CIRCUMSTANCES, BE LIABLE FOR ANY DAMAGES,
  33. INCLUDING, BUT NOT LIMITED TO, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES FOR ANY
  34. REASON WHATSOEVER.
  35. */
  36.  
  37. #include "HCWireless.h"
  38.  
  39. // Digital pin connected to the Rx modules data output pin
  40. #define RX_PIN 8
  41. // Digital pin connected to the LED
  42. #define LED_PIN 13
  43.  
  44. // Set the size of the Rx buffer in bytes (max = 255 bytes)
  45. #define RX_BUFFER_SIZE 20
  46.  
  47. // Create an instance of the library
  48. HCWireless HCWireless;
  49.  
  50.  
  51.  
  52. void setup()
  53. {
  54.   Serial.begin(9600);
  55.  
  56.   // Initialise the Rx part of the library
  57.   boolean result = HCWireless.rxInit(RX_PIN, RX_BUFFER_SIZE);
  58.  
  59.   if(!result)
  60.   {
  61.     Serial.println("Error: Can't allocate memory for Rx buffer");
  62.     while(1);
  63.   }
  64.  
  65.   pinMode(LED_PIN, OUTPUT);
  66. }
  67.  
  68.  
  69.  
  70. void loop()
  71. {
  72.   // Check to see if an LED state has been received...
  73.   if(HCWireless.available())
  74.   {
  75.     // ...if so then get the state and write it to the LED pin
  76.     boolean state = HCWireless.readByte();
  77.    
  78.     digitalWrite(LED_PIN, state);
  79.   }
  80. }





Image
HCWireless.zip




Disclaimer: Libraries, example code, and diagrams within this forum thread are provided as an additional free service by Hobby Components and are not sold as part of any product. We do not 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.
You do not have the required permissions to view the files attached to this post.

spacy
Posts: 2
Joined: Wed Oct 09, 2019 7:33 am

Re: HCWireless Arduino Library for 433MHz Wireless Tx & Rx modules

Post by spacy » Wed Oct 09, 2019 7:47 am

I get the following error in Arduino IDE when using example for HCWireless_send_text_Tx_Example:

"cannot declare member function 'static uint8_t HCWireless::available()' ..."


Two errors to be specific targeting

static uint8_t HCWireless::available(void)

static boolean HCWireless::_checkCRC(void)


Any ways to repair that?

best regards from a really much newbie in arduino and robotting

spacy
Posts: 2
Joined: Wed Oct 09, 2019 7:33 am

Re: HCWireless Arduino Library for 433MHz Wireless Tx & Rx modules

Post by spacy » Wed Oct 09, 2019 12:01 pm

I modified the code not to have STATIC in the two lines. Is this risky....

andrew
Site Admin
Posts: 1374
Joined: Sun Aug 05, 2012 4:15 pm

Re: HCWireless Arduino Library for 433MHz Wireless Tx & Rx modules

Post by andrew » Wed Oct 09, 2019 12:13 pm

I've just checked but I'm not able to replicate the error. Can you provide me the following information:

What operating system are you using ?

What version of Arduino IDE ?

What Arduino board are you compiling the sketch for ?

Can you also cut and paste the full output from the bottom of the Arduino IDE window.
Comments made by this poster do not necessarily reflect the views of Hobby Components Ltd.

oldmaker
Posts: 12
Joined: Tue Aug 08, 2023 9:04 am

Re: HCWireless Arduino Library for 433MHz Wireless Tx & Rx modules

Post by oldmaker » Mon Aug 21, 2023 4:35 pm

I wish to use this library on LG8F328P QFT32 mini EVB development board for Transmitter and Receiver. But it does not seem to work although the code compiles without error. At the receiving end the variable size always returns 0.
See code below:
In the main Loop()

byte size = HCWireless.available();
Serial.println(size);
if(size)
{
// ...if so then transfer the data out of the Rx buffer and into the structure
HCWireless.read(data);
// Print out the contents of the structure
Serial.println(data.testByte);
Serial.println(data.testInt);
Serial.println(data.testFloat);
Serial.println(data.testBoolean);
Serial.println();

}
I have used the end Text and Send Structure examples supplied with the library.

I have also used the Radiohead ASK library with success but would prefer the HCwireless library as it is possible to send data within a structure which the RadionHead ASK library cannot do. Are you aware of incompatabilities. I am reluctant to use AVR Pro-Minis as they are more expensive.

andrew
Site Admin
Posts: 1374
Joined: Sun Aug 05, 2012 4:15 pm

Re: HCWireless Arduino Library for 433MHz Wireless Tx & Rx modules

Post by andrew » Tue Aug 22, 2023 7:49 am

I wish to use this library on LG8F328P QFT32 mini EVB development board for Transmitter and Receiver. But it does not seem to work although the code compiles without error.

Yes I am afraid it will only work with ATMega328 based devices. This is because the receive side of the library needs a hardware timer interrupt to process the incoming data in the background. Unfortunately this means the library has to be hardware specific for two reasons, firstly Arduino did not implement timer interrupts into its environment. This is a shame as they are an extremely useful feature of microcontrollers! The result of this omission is that if you need a timer interrupt you have to effectively hack the Arduino environment which then breaks compatibility.

The second problem is different microcontrollers (and quite often variants of the same microcontroller) implement hardware timer interrupts in different ways. So if you need to use one in your code you either have to either implement code for each variation of microcontroller, which is not very practical, or just make the library hardware specific.

If you really need to use the LG8F328 in your project then for now the RadioHead library (formally virtualwire) will be your best solution. I’ve not used it myself but I’d expect it possible to put a wrapper around its tx/rx functions to use structures.
Comments made by this poster do not necessarily reflect the views of Hobby Components Ltd.

oldmaker
Posts: 12
Joined: Tue Aug 08, 2023 9:04 am

Re: HCWireless Arduino Library for 433MHz Wireless Tx & Rx modules

Post by oldmaker » Tue Aug 22, 2023 4:48 pm

Thanks for the reply. I'll use the RadioHead ASK library with the LGT8 MPU. The board will also be driving a NOKIA lcd display using the HCdisplay libray which it does very well exceeding the the performance of the AVR Pro-Mini.

andrew
Site Admin
Posts: 1374
Joined: Sun Aug 05, 2012 4:15 pm

Re: HCWireless Arduino Library for 433MHz Wireless Tx & Rx modules

Post by andrew » Wed Aug 23, 2023 9:58 am

Yes thanks for the feedback on the library, the Nokia screen was only recently added to it.
Comments made by this poster do not necessarily reflect the views of Hobby Components Ltd.

oldmaker
Posts: 12
Joined: Tue Aug 08, 2023 9:04 am

Re: HCWireless Arduino Library for 433MHz Wireless Tx & Rx modules

Post by oldmaker » Sat Aug 26, 2023 8:52 am

Futher to my recent post regarding using the HCWireless Library compatability with the LGT8F328P QFP32 development boards I have carried out further tests and I can confirm that the HCWireless Library is compatible with this device as long as both the TX MPU and RX MPU are set to a clock frequency of 16Mhz ie clock divider set to 2. This was tested OK using the Library Send Text Example. My initial problem was defining the TX and RX pins to other than pin8.

I have some suggestions regarding possible additional features that could be added to the libray.
1) Allow TX and TX to be defined for any pin
2) Allow the use of mpu with cpu frequency other than 16Mhz - ie 8Mhz to allow the use of the 3.3v Pro-mini or the LGT8F running at 8Mhz. This could be useful on the Tx side for low power battery operations.

Also is there a 3.3v vartiant of the Rx module?
Will you be selling the 3.3v variant of the LGT8F QFP32 development board?

Thankyou for your support

andrew
Site Admin
Posts: 1374
Joined: Sun Aug 05, 2012 4:15 pm

Re: HCWireless Arduino Library for 433MHz Wireless Tx & Rx modules

Post by andrew » Tue Aug 29, 2023 8:08 am

Futher to my recent post regarding using the HCWireless Library compatability with the LGT8F328P QFP32 development boards I have carried out further tests and I can confirm that the HCWireless Library is compatible with this device
That's quite surprising. I didn't expect it to work.

My initial problem was defining the TX and RX pins to other than pin8.
I've had a look at the library but I'm not seeing why it would only work with pin 8.

2) Allow the use of mpu with cpu frequency other than 16Mhz - ie 8Mhz to allow the use of the 3.3v Pro-mini or the LGT8F running at 8Mhz.
That's a good point. I've made an update to the library (V1.1) and attached it to this post. I'm not able to test it right now but hopefully it should detect the CPU clock speed (8, 16, 32MHz) and automatically adjust the timings appropriately. I'll add it to the first post once it's confirmed working.

HCWireless_V1_1.zip
You do not have the required permissions to view the files attached to this post.
Comments made by this poster do not necessarily reflect the views of Hobby Components Ltd.

Post Reply

Return to “Arduino”