0.2.2 RS485

libraries/RS485/README.md

@@ -66,6 +66,25 @@ resumes with listening.
 - see examples (TODO).
 
 
+#### yield()
+
+For RTOS environments the **yield()** function needs to be called 
+when code might be blocking. As the RS485 baud rate can be pretty low, 
+the **write(array, length)** function can be blocking for too long 
+so the function can call **yield()** every 4 milliseconds if enabled.
+
+To enable **yield()** uncomment the following line in **RS485.cpp**
+
+// #define RS485_YIELD_ENABLE  1
+
+or use this flag in the compile line option
+
+Note: the **yield()** calling version is substantial slower, depending 
+on the baud rate. Use with care.
+
+TODO: to be tested on ESP32 - RTOS .
+
+
 ## Future
 
 - improve documentation
@@ -74,8 +93,6 @@ resumes with listening.
   - which handshake?
   - dynamic buffer size?
   - should this be a sort of message class / struct. fixed size?
-- add **yield()** for large messages that are blocking.
-- prevent blocking if possible.
 - add examples
 - add unit tests
 

libraries/RS485/RS485.cpp

@@ -2,7 +2,7 @@
 //    FILE: RS485.cpp
 //  AUTHOR: Rob Tillaart
 //    DATE: 30-okt-2017
-// VERSION: 0.2.1
+// VERSION: 0.2.2
 // PURPOSE: Arduino library for RS485 modules (MAX485)
 //     URL: https://github.com/RobTillaart/RS485
 //
@@ -10,6 +10,8 @@
 // 0.1.x    2017-10-30  experimental versions.
 // 0.2.0    2022-05-24  first published version
 // 0.2.1    2022-05-24  add setTXmode(), setRXmode(), getMode().
+// 0.2.2    2022-05-25  rewrite blocking write(uint8_t * array, length).
+//                      added write(char * array, length). (convenience)
 
 
 #include "RS485.h"
@@ -58,16 +60,50 @@ size_t RS485::write(uint8_t c)
   return n;
 }
 
-//  TODO: fix blocking - yield() - merge above
+
+size_t RS485::write(char * array, uint8_t length)
+{
+  return write((uint8_t *)array, length);
+}
+
+
+///////////////////////////////////////////////////////
+//
+//  discussion about write and yield see 
+//  - https://github.com/RobTillaart/RS485/issues/2
+//
+
+// #define RS485_YIELD_ENABLE  1
+
+#ifdef RS485_YIELD_ENABLE
+
+// smallest and slightly fastest.
+size_t RS485::write(uint8_t * array, uint8_t length)
+{
+  uint8_t n = 0;
+  for (uint8_t i = 0; i < length; i++)
+  {
+    n += write(array[i]);
+    yield();
+  }
+  return n;
+}
+
+#else  
+
+//  0.2.1 version 
+//  no yield() calls - might be blocking...
 size_t RS485::write(uint8_t * array, uint8_t length)
 {
   setTXmode();    //  transmit mode
   size_t n = _stream->write(array, length);
-  delayMicroseconds(_microsPerByte);
+  delayMicroseconds(length * _microsPerByte);
   setRXmode();    //  receiver mode
   return n;
 }
 
+#endif
+
 
 void RS485::setMicrosPerByte(uint32_t baudRate)
 {

libraries/RS485/RS485.h

@@ -3,7 +3,7 @@
 //    FILE: RS485.h
 //  AUTHOR: Rob Tillaart
 //    DATE: 30-okt-2017
-// VERSION: 0.2.1
+// VERSION: 0.2.2
 // PURPOSE: Arduino library for RS485 modules
 //     URL: https://github.com/RobTillaart/RS485
 
@@ -11,7 +11,7 @@
 #include "Arduino.h"
 #include "ASCII_CONTROL.h"
 
-#define RS485_LIB_VERSION      (F("0.2.1"))
+#define RS485_LIB_VERSION        (F("0.2.2"))
 
 
 class RS485 : public Stream
@@ -27,16 +27,18 @@ public:
 
   uint8_t  getDeviceID()      { return _deviceID; };
 
+  //      Stream interface
+  int     available();
+  int     read();
+  int     peek();
+  void    flush();
 
-  //       Stream interface
-  int      available();
-  int      read();
-  int      peek();
-  void     flush();
-  size_t   write(uint8_t c);
-  size_t   write(uint8_t * array, uint8_t length);
+  //      Write
+  size_t  write(uint8_t c);
+  size_t  write(char * array, uint8_t length);  //  wrapper
+  size_t  write(uint8_t * array, uint8_t length);
 
-  //  set the communication direction
+  //      Mode functions
   inline void setTXmode() { digitalWrite(_sendPin, HIGH); };
   inline void setRXmode() { digitalWrite(_sendPin, LOW); };
   uint8_t     getMode()   { return digitalRead(_sendPin) == HIGH; };

libraries/RS485/examples/RS485_performance/RS485_performance.ino

@@ -0,0 +1,38 @@
+//    FILE: RS485_performance.ino
+//  AUTHOR: Rob Tillaart
+// PURPOSE: simple performance test for write(array, length)
+//     URL: https://github.com/RobTillaart/RS485
+
+#include "Arduino.h"
+#include "RS485.h"
+
+RS485 rs485(&Serial, 4);  //  uses default deviceID
+
+uint32_t start, stop = 0;
+
+void setup()
+{
+  Serial.begin(4800);
+  while (!Serial);
+  // Serial.println(__FILE__);
+
+  test(4800);
+}
+
+void loop()
+{
+}
+
+
+void test(uint32_t baudrate)
+{
+  char buffer[64] = "123456789012345678901234567890123456789012345678901234567890";
+  rs485.setMicrosPerByte(baudrate);
+  start = micros();
+  rs485.write((uint8_t *)buffer, 60);
+  stop = micros();
+  Serial.print("\nTIME: ");
+  Serial.println(stop - start);
+}
+
+// -- END OF FILE --

libraries/RS485/library.json

@@ -1,6 +1,6 @@
 {
   "name": "RS485",
-  "keywords": "RS485 SERIAL BALANCED",
+  "keywords": "RS485, serial, balanced, max485",
   "description": "RS485 library for Arduino.",
   "authors":
   [
@@ -15,7 +15,7 @@
     "type": "git",
     "url": "https://github.com/RobTillaart/RS485"
   },
-  "version": "0.2.1",
+  "version": "0.2.2",
   "license": "MIT",
   "frameworks": "arduino",
   "platforms": "*",

libraries/RS485/library.properties

@@ -1,5 +1,5 @@
 name=RS485
-version=0.2.1
+version=0.2.2
 author=Rob Tillaart <rob.tillaart@gmail.com>
 maintainer=Rob Tillaart <rob.tillaart@gmail.com>
 sentence=RS485 library for Arduino.