Mario Bambagini / ssWi

A simple wireless protocol to let my examples communicate each other. ssWi stands for Shared Slotted Wireless protocol

Dependents:   rover_car rover_pc supervisor watering_unit ... more

This library aims at implementing a simple communication protocol among nodes, abstracting from the hardware. The name ssWi stands for Shared Slotted Wireless. Wireless is part of the name, even though the library abstracts from the hardware, as the first version was entirely focused on the XBee modules and then the name has not been changed.

The communication channel is represented by ssWiChannel, an abstract class which models the channel that the transceivers access to. The concrete classes must implement the functions: init, read and write. The protocol automatically sends and receives data through the selected channel, exploiting the operting system timers. Addresses are not considered as the communication lays on broadcast transmissions.

The protocol provides the ssWiPort abstraction which is like memory areas shared among all the connected nodes. Reading from one port lets the node retrieve the last written value from the other nodes. Writing on one port means sending such value to other nodes.

Objects instantiated from ssWiSocket are the interface for allowing nodes to access the protocol ports.

/media/uploads/mariob/scheme.png

TODO:

  • improve the parsing of the received messages
  • communication tests with many nodes (so far, only 2 nodes have been tested)

Files at this revision

API Documentation at this revision

Revision 13:69ff47a83260, committed 2013-03-06

Comitter:
mariob
Date:
Wed Mar 06 08:21:41 2013 +0000
Parent:
12:f35f9195d598
Child:
14:0832655db3c1
Commit message:
added comments; MB

Changed in this revision

ssWi.cpp Show annotated file Show diff for this revision Revisions of this file
ssWi.hpp Show annotated file Show diff for this revision Revisions of this file
ssWiChannel.hpp Show annotated file Show diff for this revision Revisions of this file
ssWiPort.hpp Show annotated file Show diff for this revision Revisions of this file
ssWiSocket.hpp Show annotated file Show diff for this revision Revisions of this file
ssWiTypes.hpp Show annotated file Show diff for this revision Revisions of this file
xbee/xbee.cpp Show annotated file Show diff for this revision Revisions of this file
xbee/xbee.hpp Show annotated file Show diff for this revision Revisions of this file 
--- a/ssWi.cpp	Tue Oct 16 11:24:49 2012 +0000
+++ b/ssWi.cpp	Wed Mar 06 08:21:41 2013 +0000
@@ -1,4 +1,9 @@
-#include "ssWiChannel.hpp"
+/** \file ssWi.cpp
+ *  \brief implementation of the internal functions for mananing the protocol
+ *
+ */
+ 
+ #include "ssWiChannel.hpp"
 #include "ssWiPort.hpp"
 #include "ssWi.hpp"
 
@@ -7,24 +12,71 @@
 
 #include <map>
 
+
+
+/** \brief first byte of the header
+ *
+ * The header is composed of 3 bytes
+ */
+#define START_0 255
+
+/** \brief second byte of the header
+ *
+ * The header is composed of 3 bytes
+ */
+#define START_1 130
+
+/** \brief third byte of the header
+ *
+ * The header is composed of 3 bytes
+ */
+#define START_2 255
+
+
+/** 
+ * dimension of the buffers used by the sender and receiver procedure
+ */ 
 #define INTERNAL_BUFFER_SIZE 100
 
+
+/** \brief channel abstraction
+ *
+ * This object represent the communication channel that can be
+ * different means
+ */
+ssWiChannel* channel = NULL;
+
+/** \brief serialize read and write operations
+ *
+ * simultaneous multiple accesses to the mean are avoided
+ */
+Mutex mutexChannel;
+
+/** \brief set of registered communication ports
+ *
+ */
+std::map<int, ssWiPort> ports;
+
+/** \brief transmission rate
+ *
+ */
+int TXRate;
+
+/** \brief reading rate
+ *
+ */
+int RXRate;
+
+
+
+#ifndef NO_THREAD
+
 Thread* sender;
 Thread* receiver;
 
-ssWiChannel* channel = NULL;
-Mutex mutexChannel;
-
-std::map<int, ssWiPort> ports;
-
-int TXRate;
-int RXRate;
-
-
 void threadSender (void const* arg);
 void threadReceiver (void const* arg);
 
-
 bool ssWi_init (ssWiChannel* c, int rateTX, int rateRX)
 {
     if (channel!=NULL)
@@ -39,28 +91,6 @@
     return true;
 }
 
-bool ssWi_isActive (PortID port)
-{
-    return channel!=NULL && ports.find(port)!=ports.end();
-}
-
-bool ssWi_setPort (PortID port)
-{
-    if (channel==NULL)
-        return false;
-    ports[port];
-    return true;
-}
-
-bool ssWi_unsetPort (PortID port)
-{
-    if (!ssWi_isActive(port))
-        return false;
-    ports.erase(port);
-    return true;
-}
-
-
 void threadSender (void const* arg)
 {
     char buffer[50];
@@ -128,9 +158,34 @@
                 i += sizeof(PortValue);
                 if (ports.find(port)!=ports.end())
                     ports[port].setRXValue(value);
-            } else
-                i++;
+            }// else
+             //   i++;
         }
         Thread::wait(RXRate);
     }
 }
+#endif
+
+
+inline bool ssWi_isActive (PortID port)
+{
+    return channel!=NULL && ports.find(port)!=ports.end();
+}
+
+
+bool ssWi_setPort (PortID port)
+{
+    if (channel==NULL)
+        return false;
+    ports[port];
+    return true;
+}
+
+
+bool ssWi_unsetPort (PortID port)
+{
+    if (!ssWi_isActive(port))
+        return false;
+    ports.erase(port);
+    return true;
+}

--- a/ssWi.hpp	Tue Oct 16 11:24:49 2012 +0000
+++ b/ssWi.hpp	Wed Mar 06 08:21:41 2013 +0000
@@ -1,19 +1,19 @@
+/** \file ssWi.hpp
+ *  \brief internal functions for mananing the protocol
+ *
+ */
+
 #ifndef __SHARED_SLOTTED_WIRELESS_HPP__
 #define __SHARED_SLOTTED_WIRELESS_HPP__
 
 #include "ssWiTypes.hpp"
 
 
-#define START_0 255
-#define START_1 130
-#define START_2 255
-
-
 /** \brief number of provided ports
- *
  */
 #define N_PORTS 256
 
+
 class ssWiChannel;
 
 /** \brief Initialize the ssWi protocol
@@ -21,18 +21,38 @@
  * It is not possible to have two instances of this protocol at the same time. 
  *
  * \param c channel to be used for sending/receving data
- * \param rateTX transmission rate
- * \param rateRX receiving rate
+ * \param rateTX transmission rate (how many time every second)
+ * \param rateRX receiving rate (how many time every second)
  * \return true if the network has been correctly initialized, false otherwise
+ *
+ * \warning rx should be at least twice more frequent than tx (rateRX >= 2*rateTX)
  */
 bool ssWi_init (ssWiChannel* c, int rateTX, int rateRX);
 
+/** \brief disable the communication protocol
+ *
+ */
 void ssWi_stop ();
 
+/** \brief check if the communication port is open
+ *
+ * \param port port identified to check
+ * \return true if the port is open, false otherwise
+ */
 bool ssWi_isActive (PortID port);
 
+/** \brief open the specified port
+ *
+ * \param port port identified to open
+ * \return true if the port has been opened, false otherwise
+ */
 bool ssWi_setPort (PortID port);
 
+/** \brief free the specified port
+ *
+ * \param port port identified to close
+ * \return true if the port has been closed, false otherwise
+ */
 bool ssWi_unsetPort (PortID port);
 
 

--- a/ssWiChannel.hpp	Tue Oct 16 11:24:49 2012 +0000
+++ b/ssWiChannel.hpp	Wed Mar 06 08:21:41 2013 +0000
@@ -19,6 +19,11 @@
 protected:
 
     /** \brief Initialize the protocol
+     *
+     * \param c ssWi channel
+     * \param TXRate how may time tx every second
+     * \param RXRate how may time rx every second
+     * \return true if the channel is ready, false otherwise
      */
     bool _init (ssWiChannel* c, int TXRate, int RXRate) {
         return ssWi_init(c, TXRate, RXRate);
@@ -30,7 +35,7 @@
      *
      *  \param TXRate number of transmissions per second
      *  \param RXRate number of receptions per second
-     *  \return true if ssWi has been initialized succefully
+     *  \return true if ssWi has been initialized succefully, false otherwise
      */
     virtual bool init (int TXRate, int RXRate) = 0;
 

--- a/ssWiPort.hpp	Tue Oct 16 11:24:49 2012 +0000
+++ b/ssWiPort.hpp	Wed Mar 06 08:21:41 2013 +0000
@@ -16,7 +16,7 @@
  *  Ports are used internally to model a virtual memory are of the network.
  *  Note that a port is a dual gate memory area which means that if you write
  *  on it, the reading operation does not read that value but the one received
- *  though the network
+ *  through the network
  */
 class ssWiPort
 {

--- a/ssWiSocket.hpp	Tue Oct 16 11:24:49 2012 +0000
+++ b/ssWiSocket.hpp	Wed Mar 06 08:21:41 2013 +0000
@@ -30,10 +30,13 @@
      * If the network is not inizialized yet, the method returns false
      *
      * \param id port identifier to connect the socket with
+     * \return the created socket
      */
     static ssWiSocket* createSocket(PortID id);
 
     /** \brief read the last value read through the network on such socket
+     *
+     * \return the read value
      */
     PortValue read ();
 

--- a/ssWiTypes.hpp	Tue Oct 16 11:24:49 2012 +0000
+++ b/ssWiTypes.hpp	Wed Mar 06 08:21:41 2013 +0000
@@ -7,7 +7,7 @@
 
 /** \brief tyoe of the port IDentifier
  */
-typedef char PortID;
+typedef unsigned short int PortID;
 
 /** \brief type of the Value exchanged through the port
  */

--- a/xbee/xbee.cpp	Tue Oct 16 11:24:49 2012 +0000
+++ b/xbee/xbee.cpp	Wed Mar 06 08:21:41 2013 +0000
@@ -1,3 +1,8 @@
+/** \file xbee.cpp
+ *  \brief implementation of the ssWi channel using the XBee module
+ *
+ */
+ 
 #include "xbee.hpp"
 
 #include <sstream>
@@ -67,11 +72,11 @@
     std::stringstream s1, s2;
     string high, low;
     XBeeAddress addr;
-wait(1);
+    wait(1);
     if (!executeWithOk("+++"))
         return addr;
 
-wait(1);
+    wait(1);
 
     executeWithRes("ATDH \r", tmp);
     s1<<std::hex<<tmp;
@@ -93,10 +98,10 @@
 {
     char s[10];
     string low, high;
-wait(1);
+    wait(1);
     if (!executeWithOk("+++"))
         return false;
-wait(1);
+    wait(1);
     sprintf(s, "ATDH%s \r", addr.getHighAddr().c_str());
     //printf("%s\n\r", addr.getHighAddr().c_str());
     if (!executeWithOk(s))
@@ -141,7 +146,7 @@
 
     if (!executeWithOk("+++"))
         return false;
-wait(1);
+    wait(1);
     sprintf(s, "ATCH%d \r", channel);
     if (!executeWithOk(s))
         return false;
@@ -157,7 +162,7 @@
 
     if (!executeWithOk("+++"))
         return -1;
-wait(1);
+    wait(1);
     executeWithRes("ATCH \r", s);
     channel = atoi(s);
     if (!executeWithOk("ATCN \r"))

--- a/xbee/xbee.hpp	Tue Oct 16 11:24:49 2012 +0000
+++ b/xbee/xbee.hpp	Wed Mar 06 08:21:41 2013 +0000
@@ -1,3 +1,8 @@
+/** \file xbee.hpp
+ *  \brief header of the ssWi channel using the XBee module
+ *
+ */
+ 
 #ifndef __XBEE_MODULE_HPP__
 #define __XBEE_MODULE_HPP__
 
@@ -61,6 +66,9 @@
 
     XBeeModule (PinName tx, PinName rx, int panID, int channel);
 
+    /*
+     * specific for the XBee module
+     */
     XBeeAddress getLocalAddress () {
         return local;
     }
@@ -69,15 +77,20 @@
 
     XBeeAddress getDstAddress ();
 
-
     int getChannel ();
+    
     int getPanID ();
 
+
+    /*
+     * inherited from ssWiChannel
+     */
     virtual bool init (int TXRate, int RXRate) {
         return _init(this, TXRate, RXRate);
     }
+
+    virtual int read (char* msg);
     
-    virtual int read (char* msg);
     virtual void write (const char* msg, int n);
     
 };