Extended documentation

LocalParticipant.cpp

@@ -26,15 +26,31 @@ namespace RoboidControl {
 LocalParticipant::LocalParticipant(int port) {
   this->ipAddress = "0.0.0.0";
   this->port = port;
+  if (this->port == 0)
+    this->isIsolated = true;
 }
 
 LocalParticipant::LocalParticipant(const char* ipAddress, int port) {
-  this->ipAddress = "0.0.0.0"; //ipAddress;  // maybe this is not needed anymore, keeping it to "0.0.0.0"
+  this->ipAddress = "0.0.0.0";  // ipAddress;  // maybe this is not needed anymore, keeping it to "0.0.0.0"
   this->port = port;
-  this->remoteSite = new Participant(ipAddress, port);
+  if (this->port == 0)
+    this->isIsolated = true;
+  else
+    this->remoteSite = new Participant(ipAddress, port);
+}
+
+static LocalParticipant* isolatedParticipant = nullptr;
+
+LocalParticipant* LocalParticipant::Isolated() {
+  if (isolatedParticipant == nullptr)
+    isolatedParticipant = new LocalParticipant(0);
+  return isolatedParticipant;
 }
 
 void LocalParticipant::begin() {
+  if (this->isIsolated)
+    return;
+
   SetupUDP(this->port, this->ipAddress, this->port);
 }
 
@@ -63,28 +79,32 @@ void LocalParticipant::Update(unsigned long currentTimeMs) {
 #endif
   }
 
-  if (this->connected == false)
-    begin();
+  if (this->isIsolated == false) {
+    if (this->connected == false)
+      begin();
 
-  if (this->publishInterval > 0 && currentTimeMs > this->nextPublishMe) {
-    ParticipantMsg* msg = new ParticipantMsg(this->networkId);
-    if (this->remoteSite == nullptr)
-      this->Publish(msg);
-    else
-      this->Send(this->remoteSite, msg);
-    delete msg;
+    if (this->publishInterval > 0 && currentTimeMs > this->nextPublishMe) {
+      ParticipantMsg* msg = new ParticipantMsg(this->networkId);
+      if (this->remoteSite == nullptr)
+        this->Publish(msg);
+      else
+        this->Send(this->remoteSite, msg);
+      delete msg;
 
-    this->nextPublishMe = currentTimeMs + this->publishInterval;
+      this->nextPublishMe = currentTimeMs + this->publishInterval;
+    }
+    this->ReceiveUDP();
   }
-  this->ReceiveUDP();
 
   for (Thing* thing : this->things) {
     if (thing != nullptr) {
       thing->Update(currentTimeMs);
-      PoseMsg* poseMsg = new PoseMsg(this->networkId, thing);
-      for (Participant* sender : this->senders)
-        this->Send(sender, poseMsg);
-      delete poseMsg;
+      if (this->isIsolated == false) {
+        PoseMsg* poseMsg = new PoseMsg(this->networkId, thing);
+        for (Participant* sender : this->senders)
+          this->Send(sender, poseMsg);
+        delete poseMsg;
+      }
     }
   }
 }
@@ -273,8 +293,13 @@ void LocalParticipant::Process(Participant* sender, NameMsg* msg) {
     int nameLength = msg->nameLength;
     int stringLen = nameLength + 1;
     char* thingName = new char[stringLen];
+#if defined(_WIN32) || defined(_WIN64)
+    strncpy_s(thingName, stringLen, msg->name, stringLen - 1);  // Leave space for null terminator
+#else
     // Use strncpy with bounds checking for other platforms (Arduino, POSIX, ESP-IDF)
     strncpy(thingName, msg->name, stringLen - 1);  // Leave space for null terminator
+    thingName[stringLen - 1] = '\0';  // Ensure null termination
+#endif
     thingName[nameLength] = '\0';
     thing->name = thingName;
     std::cout << "thing name = " << thing->name << " length = " << nameLength << "\n";

LocalParticipant.h

@@ -25,15 +25,44 @@
 
 namespace RoboidControl {
 
-/// @brief A participant is device which can communicate with other participants
+/// @brief A local participant is the local device which can communicate with other participants
+/// It manages all local things and communcation with other participants.
+/// Each application has a local participant which is usually explicit in the code.
+/// An participant can be isolated. In that case it is standalong and does not communicate with other participants.
+///
+/// It is possible to work with an hidden participant by creating things without specifying a participant in the
+/// constructor (@sa RoboidControl::Thing::Thing()). In that case an hidden isolated participant is created which can be
+/// obtained using RoboidControl::LocalParticipant::Isolated().
 class LocalParticipant : public Participant {
  public:
-  char buffer[1024];
+  /// @brief Create a participant without connecting to a site
+  /// @param port The port on which the participant communicates
+  /// These participant typically broadcast Participant messages to let site servers on the local network know their presence.
+  /// Alternatively they can broadcast information which can be used directly by other participants.
+  LocalParticipant(int port = 7681);
+  /// @brief Create a participant which will try to connect to a site.
+  /// @param ipAddress The IP address of the site
+  /// @param port The port used by the site
+  LocalParticipant(const char* ipAddress, int port = 7681);
+  // Note to self: one cannot specify the port used by the local participant now!!
+
+  /// @brief Isolated participant is used when the application is run without networking
+  /// @return A participant without networking support
+  static LocalParticipant* Isolated();
+
+  /// @brief True if the participant is running isolated.
+  /// Isolated participants do not communicate with other participants
+  bool isIsolated = false;
+
+  /// The interval in milliseconds for publishing (broadcasting) data on the local network
   long publishInterval = 3000;  // 3 seconds
 
+  /// @brief The name of the participant
   const char* name = "LocalParticipant";
 
   // int localPort = 0;
+
+  /// @brief The remote site when this participant is connected to a site
   Participant* remoteSite = nullptr;
 
 #if defined(ARDUINO)
@@ -44,9 +73,7 @@ class LocalParticipant : public Participant {
   WiFiUDP udp;
 #else
 
-#if defined(_WIN32) || defined(_WIN64)
-  SOCKET sock;
-#elif defined(__unix__) || defined(__APPLE__)
+#if defined(__unix__) || defined(__APPLE__)
   int sock;
 #endif
   sockaddr_in remote_addr;
@@ -55,9 +82,6 @@ class LocalParticipant : public Participant {
 
 #endif
 
-  LocalParticipant(int port = 7681);
-  LocalParticipant(const char* ipAddress, int port = 7681);
-
   void begin();
   bool connected = false;
 
@@ -77,6 +101,8 @@ class LocalParticipant : public Participant {
  protected:
   unsigned long nextPublishMe = 0;
 
+  char buffer[1024];
+
   void SetupUDP(int localPort, const char* remoteIpAddress, int remotePort);
 
   Participant* GetParticipant(const char* ipAddress, int port);

Participant.cpp

@@ -11,7 +11,11 @@ Participant::Participant(const char* ipAddress, int port) {
   int addressLength = strlen(ipAddress);
   int stringLength = addressLength + 1;
   char* addressString = new char[stringLength];
+#if defined(_WIN32) || defined(_WIN64)
+  strncpy_s(addressString, stringLength, ipAddress, addressLength);  // Leave space for null terminator
+#else
   strncpy(addressString, ipAddress, addressLength);
+#endif
   addressString[addressLength] = '\0';
 
   this->ipAddress = addressString;
@@ -24,7 +28,7 @@ Participant::~Participant() {
 
 Thing* Participant::Get(unsigned char networkId, unsigned char thingId) {
   for (Thing* thing : this->things) {
-    //if (thing->networkId == networkId && thing->id == thingId)
+    // if (thing->networkId == networkId && thing->id == thingId)
     if (thing->id == thingId)
       return thing;
   }
@@ -36,9 +40,10 @@ Thing* Participant::Get(unsigned char networkId, unsigned char thingId) {
 void Participant::Add(Thing* thing, bool checkId) {
   if (checkId && thing->id == 0) {
     // allocate a new thing ID
-    thing->id = this->things.size() + 1;
+    thing->id = (unsigned char)this->things.size() + 1;
     this->things.push_back(thing);
-    // std::cout << "Add thing with generated ID " << this->ipAddress << ":" << this->port << "[" << (int)thing->networkId << "/"
+    // std::cout << "Add thing with generated ID " << this->ipAddress << ":" << this->port << "[" <<
+    // (int)thing->networkId << "/"
     //           << (int)thing->id << "]\n";
   } else {
     Thing* foundThing = Get(thing->networkId, thing->id);
@@ -58,16 +63,16 @@ void Participant::Remove(Thing* thing) {
   std::cout << "Removing " << thing->networkId << "/" << thing->id << " list size = " << this->things.size() << "\n";
 }
 
-void Participant::UpdateAll(unsigned long currentTimeMs) {
-  // Not very efficient, but it works for now.
+// void Participant::UpdateAll(unsigned long currentTimeMs) {
+//   // Not very efficient, but it works for now.
 
-  for (Thing* thing : this->things) {
-    if (thing != nullptr && thing->GetParent() == nullptr) {  // update all root things
-      // std::cout << " update " << (int)ix << " thingid " << (int)thing->id
-      //           << "\n";
-      thing->Update(currentTimeMs);
-    }
-  }
-}
+//   for (Thing* thing : this->things) {
+//     if (thing != nullptr && thing->GetParent() == nullptr) {  // update all root things
+//       // std::cout << " update " << (int)ix << " thingid " << (int)thing->id
+//       //           << "\n";
+//       thing->Update(currentTimeMs);
+//     }
+//   }
+// }
 
 }  // namespace RoboidControl

Participant.h

@@ -3,25 +3,50 @@
 
 namespace RoboidControl {
 
+/// @brief A participant is a device which manages things.
+/// It can communicate with other participant to synchronise the state of things.
+/// This class is used to register the things the participant is managing.
+/// It also maintains the communcation information to contact the participant.
+/// It is used as a basis for the local participant, but also as a reference to remote participants.
 class Participant {
 public:
+  /// @brief The Ip Address of a participant. When the participant is local, this contains 0.0.0.0
   const char *ipAddress = "0.0.0.0";
+  /// @brief The port number for UDP communication with the participant. This is 0 for isolated participants.
   int port = 0;
 
+  /// @brief The network Id to identify the participant.
+  /// @note This field is likely to disappear in future versions
   unsigned char networkId = 0;
 
+  /// @brief Default constructor
   Participant();
+  /// @brief Create a new participant with the given communcation info
+  /// @param ipAddress The IP address of the participant
+  /// @param port The port of the participant
   Participant(const char *ipAddress, int port);
+  /// @brief Destructor for the participant
   ~Participant();
 
 protected:
+  /// @brief The list of things managed by this participant
   std::list<Thing *> things;
 
 public:
+  /// @brief Find a thing managed by this participant
+  /// @param networkId The network ID for the thing
+  /// @param thingId The ID of the thing
+  /// @return The thing if found or nullptr when no thing has been found
+  /// @note The use of the network ID is likely to disappear in future versions.
   Thing *Get(unsigned char networkId, unsigned char thingId);
+  /// @brief Add a new thing for this participant. 
+  /// @param thing The thing to add
+  /// @param checkId Checks the thing ID of the thing. If it is 0, a new thing Id will be assigned.
   void Add(Thing *thing, bool checkId = true);
+  /// @brief Remove a thing for this participant
+  /// @param thing The thing to remove
   void Remove(Thing *thing);
-  void UpdateAll(unsigned long currentTimeMs);
+
 };
 
 } // namespace Control

README.md

@@ -5,7 +5,7 @@ Supporting:
 - Windows
 - MacOS
 - Linux
-- Arduino (using PlatformIO)
+- Arduino (using PlatformIO). The following microcontrollers are tested and supported:
     - ESP8266
     - ESP32
     - UNO R4 WiFi
@@ -13,5 +13,5 @@ Supporting:
 # Basic components
 
 - RoboidControl::Thing
-- RoboidControl::Participant
+- RoboidControl::LocalParticipant
 - RoboidControl::SiteServer

Thing.cpp

@@ -9,21 +9,21 @@
 #include "LocalParticipant.h"
 
 namespace RoboidControl {
-static LocalParticipant* hiddenParticipant = nullptr;
 
-LocalParticipant* Thing::CheckHiddenParticipant() {
-  if (hiddenParticipant == nullptr)
-    hiddenParticipant = new LocalParticipant(0);
-  return hiddenParticipant;
-}
 
-Thing::Thing(int thingType) : Thing(CheckHiddenParticipant(), thingType) {
+// LocalParticipant* Thing::CheckHiddenParticipant() {
+//   if (isolatedParticipant == nullptr)
+//     isolatedParticipant = new LocalParticipant(0);
+//   return isolatedParticipant;
+// }
+
+Thing::Thing(int thingType) : Thing(LocalParticipant::Isolated(), thingType) {
 }
 
 Thing::Thing(Participant* owner, Type thingType) : Thing(owner, (unsigned char)thingType) {}
 
 Thing::Thing(Participant* owner, int thingType) {
-  this->participant = owner;
+  this->owner = owner;
   this->id = 0;
   this->type = thingType;
   this->networkId = 0;
@@ -40,7 +40,7 @@ Thing::Thing(Participant* owner, int thingType) {
 
 Thing::Thing(Participant* owner, unsigned char networkId, unsigned char thingId, Type thingType) {
   // no participant reference yet..
-  this->participant = owner;
+  this->owner = owner;
   this->networkId = networkId;
   this->id = thingId;
   this->type = (unsigned char)thingType;
@@ -172,11 +172,13 @@ unsigned long Thing::GetTimeMs() {
   return static_cast<unsigned long>(ms.count());
 }
 
-#if defined(ARDUINO)
 void Thing::Update() {
+  #if defined(ARDUINO)
   Update(millis());
+  #else
+  Update(GetTimeMs());
+  #endif
 }
-#endif
 
 void Thing::Update(unsigned long currentTimeMs) {
   (void)currentTimeMs;
@@ -188,10 +190,7 @@ void Thing::Update(unsigned long currentTimeMs) {
 }
 
 void Thing::UpdateThings(unsigned long currentTimeMs) {
-  if (hiddenParticipant == nullptr)
-  return;
-
-  hiddenParticipant->Update(currentTimeMs);
+  LocalParticipant::Isolated()->Update(currentTimeMs);
 }
 
 void Thing::GenerateBinary(char* buffer, unsigned char* ix) {

Thing.h

@@ -51,16 +51,16 @@ class Thing {
   /// @param thingType The type of thing
   Thing(Participant* participant, unsigned char networkId, unsigned char thingId, Type thingType = Type::Undetermined);
 
- private:
-  LocalParticipant* CheckHiddenParticipant();
-
- public:
-  Participant* participant;  // -> owner
+  /// @brief The participant managing this thing
+  Participant* owner;
+  /// @brief The network ID of this thing
+  /// @note This field will likely disappear in future versions
   unsigned char networkId = 0;
   /// @brief The ID of the thing
   unsigned char id = 0;
 
   /// @brief The type of Thing
+  /// This can be either a Thing::Type of a byte value for custom types
   unsigned char type = 0;
 
   /// @brief Find a thing by name
@@ -123,7 +123,7 @@ class Thing {
   /// @return The orienation in local space
   SwingTwist16 GetOrientation();
   /// @brief The scale of the thing (deprecated I think)
-  float scale = 1;  // assuming uniform scale
+  //float scale = 1;  // assuming uniform scale
 
   /// @brief boolean indicating if the position was updated
   bool positionUpdated = false;
@@ -172,9 +172,8 @@ class Thing {
   void SetModel(const char* url);
 
   static unsigned long GetTimeMs();
-#if defined(ARDUINO)
+
   void Update();
-#endif
 
   /// @brief Updates the state of the thing
   /// @param currentTimeMs The current clock time in milliseconds

Windows/WindowsParticipant.h

@@ -11,6 +11,9 @@ class LocalParticipant : public RoboidControl::LocalParticipant {
   void Receive();
   bool Send(Participant* remoteParticipant, int bufferSize);
   bool Publish(IMessage* msg);
+
+ protected:
+  SOCKET sock;
 };
 
 }  // namespace Windows

test/participant_test.cc

@@ -52,63 +52,63 @@ protected:
 
 
 
-TEST_F(ParticipantSuite, LocalParticipant) {
-  LocalParticipant* participant = new LocalParticipant("127.0.0.1", 7681);
+// TEST_F(ParticipantSuite, LocalParticipant) {
+//   LocalParticipant* participant = new LocalParticipant("127.0.0.1", 7681);
 
-  unsigned long milliseconds = get_time_ms();
-  unsigned long startTime = milliseconds;
-  while (milliseconds < startTime + 1000) {
-    participant->Update(milliseconds);
+//   unsigned long milliseconds = get_time_ms();
+//   unsigned long startTime = milliseconds;
+//   while (milliseconds < startTime + 1000) {
+//     participant->Update(milliseconds);
 
-    milliseconds = get_time_ms();
-  }
-  ASSERT_EQ(1, 1);
-}
+//     milliseconds = get_time_ms();
+//   }
+//   ASSERT_EQ(1, 1);
+// }
 
-TEST_F(ParticipantSuite, SiteServer) {
-  SiteServer site = SiteServer(7681);
+// TEST_F(ParticipantSuite, SiteServer) {
+//   SiteServer site = SiteServer(7681);
 
-  unsigned long milliseconds = get_time_ms();
-  unsigned long startTime = milliseconds;
-  while (milliseconds < startTime + 1000) {
-    site.Update(milliseconds);
+//   unsigned long milliseconds = get_time_ms();
+//   unsigned long startTime = milliseconds;
+//   while (milliseconds < startTime + 1000) {
+//     site.Update(milliseconds);
 
-    milliseconds = get_time_ms();
-  }
-  ASSERT_EQ(1, 1);
-}
+//     milliseconds = get_time_ms();
+//   }
+//   ASSERT_EQ(1, 1);
+// }
 
-TEST_F(ParticipantSuite, SiteParticipant) {
-  SiteServer site = SiteServer(7681);
-  LocalParticipant participant = LocalParticipant("127.0.0.1", 7681);
+// TEST_F(ParticipantSuite, SiteParticipant) {
+//   SiteServer site = SiteServer(7681);
+//   LocalParticipant participant = LocalParticipant("127.0.0.1", 7681);
 
-  unsigned long milliseconds = get_time_ms();
-  unsigned long startTime = milliseconds;
-  while (milliseconds < startTime + 1000) {
-    site.Update(milliseconds);
-    participant.Update(milliseconds);
+//   unsigned long milliseconds = get_time_ms();
+//   unsigned long startTime = milliseconds;
+//   while (milliseconds < startTime + 1000) {
+//     site.Update(milliseconds);
+//     participant.Update(milliseconds);
 
-    std::this_thread::sleep_for(std::chrono::milliseconds(100));
-    milliseconds = get_time_ms();
-  }
-  ASSERT_EQ(1, 1);
-}
+//     std::this_thread::sleep_for(std::chrono::milliseconds(100));
+//     milliseconds = get_time_ms();
+//   }
+//   ASSERT_EQ(1, 1);
+// }
 
-TEST_F(ParticipantSuite, Thing) {
-  SiteServer site = SiteServer(7681);
-  LocalParticipant participant = LocalParticipant("127.0.0.1", 7681);
-  Thing thing = Thing(&participant);
+// TEST_F(ParticipantSuite, Thing) {
+//   SiteServer site = SiteServer(7681);
+//   LocalParticipant participant = LocalParticipant("127.0.0.1", 7681);
+//   Thing thing = Thing(&participant);
 
-  unsigned long milliseconds = get_time_ms();
-  unsigned long startTime = milliseconds;
-  while (milliseconds < startTime + 1000) {
-    site.Update(milliseconds);
-    participant.Update(milliseconds);
+//   unsigned long milliseconds = get_time_ms();
+//   unsigned long startTime = milliseconds;
+//   while (milliseconds < startTime + 1000) {
+//     site.Update(milliseconds);
+//     participant.Update(milliseconds);
 
-    std::this_thread::sleep_for(std::chrono::milliseconds(100));
-    milliseconds = get_time_ms();
-  }
-  ASSERT_EQ(1, 1);
-}
+//     std::this_thread::sleep_for(std::chrono::milliseconds(100));
+//     milliseconds = get_time_ms();
+//   }
+//   ASSERT_EQ(1, 1);
+// }
 
 #endif

test/thing_test.cc

@@ -4,14 +4,12 @@
 // not supported using Visual Studio 2022 compiler...
 #include <gtest/gtest.h>
 
-// #include <chrono>
-// #include <thread>
-
+#include "LocalParticipant.h"
 #include "Thing.h"
 
 using namespace RoboidControl;
 
-TEST(RoboidControlSuite, LocalParticipant) {
+TEST(RoboidControlSuite, HiddenParticipant) {
   Thing* thing = new Thing();
 
   unsigned long milliseconds = Thing::GetTimeMs();
@@ -24,5 +22,18 @@ TEST(RoboidControlSuite, LocalParticipant) {
   SUCCEED();
 }
 
+TEST(RoboidControlSuite, IsolatedParticipant) {
+  LocalParticipant* participant = LocalParticipant::Isolated();
+  Thing* thing = new Thing(participant);
+
+  unsigned long milliseconds = Thing::GetTimeMs();
+  unsigned long startTime = milliseconds;
+  while (milliseconds < startTime + 1000) {
+    participant->Update(milliseconds);
+
+    milliseconds = Thing::GetTimeMs();
+  }
+  SUCCEED();
+}
 
 #endif