EasyTransfer Arduino Library

Posted in Arduino Libraries by Bill
30 May 2011
EasyTransfer Arduino Library

The purpose of this library is to make it easy for the everyday Arduino user working on projects with multiple Arduinos communicating with each other and sharing data. I had many people ask me for the code I used in my PS2X library example that sent PS2 Controller values wirelessly to my SAGAR robot. It got to be tiresome answering the questions and I had an idea to write a library to help the inexperienced with micro controller communications. This is a easy to use and no frills way to send data between two Arduinos.

In most of my own projects I define and write my own NMEA standard communication protocols. This makes communications human readable and easy to debug, but proves wasteful with bandwidth and processing power so it’s not right for every application. Binary communications is much more efficient and versatile, but requires careful handling. This library abstracts the finer points of packetized serial communication away from the user so it easy to use and understand.

To use the library, simple define all the data types you want to share inside a data structure. This keeps all the data stored together in memory.

struct SEND_DATA_STRUCTURE{
  //put your variable definitions here for the data you want to send
  //THIS MUST BE EXACTLY THE SAME ON THE OTHER ARDUINO
  int blinks;
  int pause;
};

When requested, the library will send all the binary data in the structure to another Arduino via serial with a checksum to avoid transfer errors.

void loop(){
  //this is how you access the variables. [name of the group].[variable name]
  mydata.blinks = random(5);
  mydata.pause = random(5);
  //send the data
  ET.sendData();
  delay(10000);
}

The receiving Arduino will verify the checksum, and copy the new data onto a identical structure in it’s memory.

void loop(){
  //check and see if a data packet has come in. 
  if(ET.receiveData()){
    //this is how you access the variables. [name of the group].[variable name]
    //since we have data, we will blink it out. 
    for(int i = mydata.blinks; i>0; i--){
      digitalWrite(13, HIGH);
      delay(mydata.pause * 100);
      digitalWrite(13, LOW);
      delay(mydata.pause * 100);
    }
  }

  delay(2500);
}

It’s important to make sure the structure is the same on both Arduinos for this to work. Now sharing data between Arduinos is easy without having to define and program your own communications protocol and have to worry about syncing or transmit errors. EasyTransfer will do that for you.

Using Structures to hold the data allows for versatile communications by allowing any type and number of data points to be shared, as long as the whole structure is under 255 bytes. You could define int’s, arrays, longs, etc inside the structure and share the data. It’s also possible to create two way communications by defining two sets of structs on each end and creating two objects using the library. I will have an example of that up shortly.

You can download the library and example below. The example requires two Arduino boards to be connected to each other via their Uarts. One will create two random numbers and send the data to the other that will flash out a sequence of flashes based on those numbers. The first one will also flash out the same sequence.

Now it’s easier to pick which Serial port to use; Serial, Serial1, etc. AND support for the NewSoftSerial library for creating software serial ports on any pin. EasyTransfer is for hardware serial, SoftEasyTransfer is for software; each has there own set of examples. There’s also an example for two way communications using the library.

Source Code available on GitHub project pages.

 

Or Direct Download

 

UPDATE

Thanks to Kumy, there’s now an I2C version of EasyTransfer. There’s also an experimental VirtualWire version for use with those cheap low frequency radios. All are in the single download zip file above.

 

To install the Library, open the zip file and transfer the EasyTransfer folder into your Arduino ‘libraries’ folder. Then follow the examples to add the code to your project. If you have any problems or questions, let me know in the Support Forum.

Need Help?

Please use the Support Forum to ask for help. Don’t use the comments below.

 

Creative Commons License
This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.

Share

Warning: count(): Parameter must be an array or an object that implements Countable in /homepages/46/d285670699/htdocs/bill/wp-includes/comment.php on line 879
  1. 443 Comments.

    • JarmilNo Gravatar says:

      Hello
      at the new library does not EasyTransfer example EasyTransfer example RX or TX example.

      EasyTransfer_TX_Example:4: error: ‘EasyTransfer’ does not name a type
      EasyTransfer_TX_Example.pde: In function ‘void setup()’:
      EasyTransfer_TX_Example:19: error: ‘ET’ was not declared in this scope
      EasyTransfer_TX_Example:19: error: ‘details’ was not declared in this scope

      Please fix it?

    • Troubleshooters UnlimitedNo Gravatar says:

      Hello Bill. Although this post is not so young anymore, I decided to log in just to say thank you for your brilliant contribution. Your EasyTransfer library is truly helpful in many ways and it just saved me important time as I connected six ATMEGA328 microcontrollers together through the I2C bus in order for them to share relevant amounts of data with each other. For the time being, all I can say is that I cannot thank you enough for your thoughtfulness, for your generosity, and for your inspiring creativity. More so, just as youngsters say nowadays, you are truly the man! Thank you Mr. Porter.

      Now, on a parallel line of thought, and as a merely poor-strive to help others in using your clever library, I’d like to share my experience when I was striving to send 18 floating-point variables from the master to one of the other five slaves within my arrange. Taking into consideration that each floating number is comprised of 4 bytes, it is correct to say that I was striving to send a data package at least 72 bytes long. As you already know, under normal circumstances and unmodified libraries on any kind within the Arduino realm, the maximum size for the data stream to share via the I2C bus is normally limited to 28 bytes per each data-sharing object created through your library and, beyond that, things just get “blank” for the microcontrollers and “nasty” for whoever needs a broader communications’ width-band.

      After a “fortunate” analysis, just to frame my sad situation within the words’ domain, and after the dust of my deep disappointment settled down, I undertook the challenge of writing down my own communications protocol. That way, after the initial cursing episode gave in, I began by deciphering, not to say “by striving to understand” the “wire” library, in a modest attempt to use it as the foundation for whatever code I could come up with. To my surprise, I did not need to go far on this matter, for I noticed right from the start, that the “wire” library sets 32 bytes-long data-buffers to deal with whatever it needs to deal when it is summoned to work. It turned out that the window of opportunity was not shut to me after all and, to get my feet wet, so to speak, I began by changing the “wire” library’s buffers’ sizes to accommodate things for my particular needs. As I ran my sketch once more, your outstanding code took care of the rest, and the six microcontrollers were now exchanging data related to 18 floating point variables! Evidently, the larger buffers’ sizes within the “wire” library yielded in larger memory demands for the microcontrollers; nevertheless, the changes work seamless for as long as I do not exceed the controllers’ memory capacities and for as long as I leave enough dynamic memory left for them to function properly. Once again, thank you very much Mr. Porter…

    • Irwan AdinathaNo Gravatar says:

      Hi Bill,

      Thank you for sharing the library, as a beginner yours packet over serial is easiest to use.
      However, I do have some troubles in using it correctly.

      Here is my struct
      struct SEND_DATA_STRUCTURE {
      uint8_t currSpeedFront; //highest speed is 255
      uint8_t currSpeedBack;
      uint8_t maxSpeedFront; //highest speed is 255
      uint8_t maxSpeedBack;
      uint16_t currAltitudeFront; //highes altitude is 65535
      uint8_t currAltitudeBack;
      uint8_t numberOfSats;
      };

      the data of the currAlititudeFront overflow at 255. Is byte is the maximum length I can use for each data ?

    • Hi Bill.
      I would like to try your softEasyTransfer using some cheap “RS485”-boards from Ebay.
      However, I need to use pins 3, 4, 6 as direction control, serial receive and serial transmit, respectively.
      Where in the code do I specify that?

      A short explanation of how I do it in my most recent code:
      When using SoftwareSerial I specify these pins when I start the library:
      //SoftwareSerial RS485Serial(SSerialRX, SSerialTX);
      SoftwareSerial RS485Serial(4,6);

      And I enable or disable the transmit by setting pin 3 (direction control) to high or low
      //digitalWrite(SSerialTxControl, RS485Transmit); // Enable RS485 Transmit
      digitalWrite(3, HIGH);

      Thanks for a superb and FREE code!

    • DE CLARKENo Gravatar says:

      Just wanted to echo the bouquets and thanks from others. I2C is tremendously powerful and useful and … kind of squirrelly and tetchy for Arduino n00bs to use successfully. Your library is exactly what I need for my project. Many thanks for your contribution to a fantastic community.

    • andreasNo Gravatar says:

      Hi, is it possible to use SoftEasyTransfer to transmit and EasyTransfer to receive? Are they compatible to each other?

      Thanks!

    • Hello Arduino Community!

      First of all, let me say thank you to Bill Porter for this amazing library. It makes transferring information so easy! I have a quick question. I am trying to transfer a string from Arduino to Arduino and every time it just sends an error. I don’t know what the problem is! Any help is welcome. Thank you in advance!!

    • MatejNo Gravatar says:

      Hi, I am having a problem with easyTransfer library.

      I tried copying it into libraries but the .h file declaration doesn’t color as recognised even after IDE restart.

      If i try to import it from zip IDE says:

      Specified folder/zip file does not contain a valid library.

      Plese help

    • MaximeDupNo Gravatar says:

      Hello Bill,
      first, like many here, thank you very much for this super useful piece of code!

      I have the library working well for months but I’m trying something a bit more “challenging” and I’m a bit stuck..

      I have one sending structure and one receiving structure, it works well. But i need to send a int array[127], so being the very max size of one structure (these are value from a sensor i need to send at the end of a measurement)

      So I tried to add a new structure, just for sending this array, but when i call the sendData() for this structure, it works if I call it first, but it misses if I call the sendData() of the other structure before.

      here are the structure on the master :

      struct SEND_COURBE{
      int crb_exp[127];//valeurs de la courbe
      };
      SEND_COURBE txcrb;
      struct SEND_DATA_STRUCTURE{
      char tref[14];//reference
      float tminit;//masse initiale
      int duree;//min durée
      float tmfin;//masse finale
      float thumi;//humidite
      int exporta;//bit de validation
      };
      SEND_DATA_STRUCTURE txdata;

      struct RECEIVE_DATA_STRUCTURE{
      int check;
      int conn;
      };
      RECEIVE_DATA_STRUCTURE rxdata;

      //////

      ETout.begin(details(txdata), &myS);
      ETin.begin(details(rxdata), &myS);
      ETcrb.begin(details(txcrb), &myS);

      And on the other side :

      struct REC_COURBE {
      int crb_exp[127];//valeurs de la courbe
      };
      REC_COURBE txcrb;

      struct RECEIVE_DATA_STRUCTURE {
      char tref[14];
      float tminit;
      int duree;
      float tmfin;
      float thumi;
      int exporta;
      };
      RECEIVE_DATA_STRUCTURE rxdata;

      struct SEND_DATA_STRUCTURE {
      int check;
      int conn;
      };

      SEND_DATA_STRUCTURE txdata;

      //////
      ETin.begin(details(rxdata), &mySerial);
      ETout.begin(details(txdata), &mySerial);
      ETcrb.begin(details(txcrb), &mySerial);

      Is it something that is impossible to achieve, or am I missing something ?

      I read some discussion in the comment where someone was trying to do this and he finally ended up putting more variables in the existing structure, which is impossible for me because of the size of the array I need to send..

      thank you for any assistance ! 🙂

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.