Merge pull request #4 from avilleret/feature/SLIPEncoding

add SLIP encoding

Author: bakercp

README.md

@@ -1,7 +1,7 @@
 PacketSerial
 ============
 
-_PacketSerial_ is an small, efficient, library that allows [Arduinos](http://www.arduino.cc/) to send and receive serial data packets that include bytes with any value (0-255).  A _packet_ is simply an array of bytes.
+_PacketSerial_ is an small, efficient, library that allows [Arduinos](http://www.arduino.cc/) to send and receive serial data packets (with COBS or SLIP encoding) that include bytes with any value (0-255).  A _packet_ is simply an array of bytes.
 
 _"Why do I need this?"_ you may ask.  The truth is that you may not need it if you are converting your values to ASCII strings and separating them with a known character (like a new line `\n`) before sending them.   This is what happens if you call `Serial.print()` or `Serial.println()`.  For instance, if you just want to send a byte with the value of 255 and follow it with a new line character (i.e. `Serial.println(255)`) the Arduino automatically converts the number to the equivalent printable ASCII characters, sending 4 bytes total.  As a result the receiver won't just receive a byte for the number and a byte for the new line character.  Instead it will receive a stream of 4 bytes:
 
@@ -44,7 +44,8 @@ An alternative to ASCII encoding is to write the bytes directly to using the `Se
 10  // The new line character (\n).
 ```
 
-This is much more compact but can create problems when the user wants to send a _packet_ of data.  If the user wants to send a packet consisting of two values such as 255 and 10, we run into problems if we also use the new line ('\n' ASCII 10) character as a packet boundary.  This essentially means that the receiver will incorrectly think that a new packet is beginning when it receives the _value_ of 10.  Thus, to use this more compact form of sending bytes while reserving one value for a packet boundary marker.  Several unambiguous packet boundary marking encodings exist, but one with a small predictable overhead is called [Consistent Overhead Byte Stuffing](http://en.wikipedia.org/wiki/Consistent_Overhead_Byte_Stuffing).  For a raw packet of length `SIZE`, the maximum encoded buffer size will only be `SIZE + SIZE / 254 + 1`.  This is significantly less than ASCII encoding and the encoding / decoding algorithm is simple and fast.  In its default mode, the COBS encoding process simply removes all _zeros_ from the packet, allowing the sender and receiver to use the value of _zero_ as a packet boundary marker.  
+This is much more compact but can create problems when the user wants to send a _packet_ of data.  If the user wants to send a packet consisting of two values such as 255 and 10, we run into problems if we also use the new line ('\n' ASCII 10) character as a packet boundary.  This essentially means that the receiver will incorrectly think that a new packet is beginning when it receives the _value_ of 10.  Thus, to use this more compact form of sending bytes while reserving one value for a packet boundary marker.  Several unambiguous packet boundary marking encodings exist, but one with a small predictable overhead is called [Consistent Overhead Byte Stuffing](http://en.wikipedia.org/wiki/Consistent_Overhead_Byte_Stuffing).  For a raw packet of length `SIZE`, the maximum encoded buffer size will only be `SIZE + SIZE / 254 + 1`.  This is significantly less than ASCII encoding and the encoding / decoding algorithm is simple and fast.  In its default mode, the COBS encoding process simply removes all _zeros_ from the packet, allowing the sender and receiver to use the value of _zero_ as a packet boundary marker.
+Another coding available in PacketSerial is [Serial Line Internet Protocol](https://en.wikipedia.org/wiki/Serial_Line_Internet_Protocol) which is often used to send OSC over serial or TCP connection. To use SLIP encoding instead of COBS, use `SLIPPacketSerial` instead of `PacketSerial`. You can find some example about sending OSC data over serial in the [ofxSerial](https://github.com/bakercp/ofxSerial) repository.
 
 ## PacketSerial
 

src/Encoding/SLIP.h

@@ -0,0 +1,151 @@
+// =============================================================================
+//
+// Copyright (c) 2010-2014 Christopher Baker <http://christopherbaker.net>
+// 2016 Antoine Villeret added Christopher's ofx/IO/SLIPEncoding.h here
+//
+// see : https://github.com/bakercp/ofxIO/blob/master/libs/ofxIO/include/ofx/IO/SLIPEncoding.h
+//
+// Portions:
+//  Copyright (c) 2011, Jacques Fortier. All rights reserved.
+//  https://github.com/jacquesf/COBS-Consistent-Overhead-Byte-Stuffing
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+//
+// =============================================================================
+
+
+#pragma once
+
+
+#include "Arduino.h"
+
+
+
+/// \brief A Serial Line IP (SLIP) Encoder.
+///
+/// Serial Line IP (SLIP) is a packet framing protocol: SLIP defines a
+/// sequence of characters that frame IP packets on a serial line and
+/// nothing more. It provides no addressing, packet type identification,
+/// error detection/correction or compression mechanisms.  Because the
+/// protocol does so little, though, it is usually very easy to
+/// implement.
+///
+/// \sa http://tools.ietf.org/html/rfc1055
+class SLIP
+{
+public:
+    static size_t encode(const uint8_t* buffer, size_t size, uint8_t* encoded)
+    {
+        if (size == 0)
+            return 0;
+
+        size_t read_index  = 0;
+        size_t write_index = 0;
+
+        // double-ENDed, flush any data that may have accumulated due to line noise
+        encoded[write_index++] = END;
+
+        while (read_index < size)
+        {
+            if(buffer[read_index] == END)
+            {
+                encoded[write_index++] = ESC;
+                encoded[write_index++] = ESC_END;
+                read_index++;
+            }
+            else if(buffer[read_index] == ESC)
+            {
+                encoded[write_index++] = ESC;
+                encoded[write_index++] = ESC_ESC;
+                read_index++;
+            }
+            else
+            {
+                encoded[write_index++] = buffer[read_index++];
+            }
+        }
+
+        encoded[write_index++] = END;
+
+        return write_index;
+    }
+
+    static size_t decode(const uint8_t* buffer, size_t size, uint8_t* decoded)
+    {
+        if (size == 0)
+            return 0;
+
+        size_t read_index  = 0;
+        size_t write_index = 0;
+
+        while (read_index < size)
+        {
+            if (buffer[read_index] == END)
+            {
+                // flush or done
+                read_index++;
+            }
+            else if (buffer[read_index] == ESC)
+            {
+                if (buffer[read_index+1] == ESC_END)
+                {
+                    decoded[write_index++] = END;
+                    read_index += 2;
+                }
+                else if (buffer[read_index+1] == ESC_ESC)
+                {
+                    decoded[write_index++] = ESC;
+                    read_index += 2;
+                }
+                else
+                {
+                    // considered a protocol violation
+                }
+            }
+            else
+            {
+                decoded[write_index++] = buffer[read_index++];
+            }
+        }
+
+        return write_index;
+    }
+
+    /// \brief Get the maximum encoded buffer size needed for a given source size.
+    ///
+    /// SLIP has a start and a end markers (192 and 219).
+    /// Marker value is replaced by 2 bytes in the encoded buffer.
+    /// So in the worst case of sending a buffer with only '192' or '219',
+    /// the encoded buffer length will be 2 * buffer.size() + 2
+    /// \param sourceSize The size of the buffer to be encoded.
+    /// \returns the maximum size of the required encoded buffer.
+    static size_t getEncodedBufferSize(size_t sourceSize)
+    {
+        return sourceSize * 2 + 2;
+    }
+
+    enum
+    {
+        END = 0300,
+        ESC = 0333,
+        ESC_END = 0334,
+        ESC_ESC = 0335
+    };
+
+};

src/PacketSerial.h

@@ -27,6 +27,7 @@
 
 #include <Arduino.h>
 #include "Encoding/COBS.h"
+#include "Encoding/SLIP.h"
 
 
 template<typename EncoderType, uint8_t PacketMarker = 0, int BufferSize = 256>
@@ -145,4 +146,6 @@ class PacketSerial_
 };
 
 
-typedef PacketSerial_<COBS> PacketSerial;
+ typedef PacketSerial_<COBS> PacketSerial;
+ typedef PacketSerial_<COBS> COBSPacketSerial;
+ typedef PacketSerial_<SLIP, SLIP::END> SLIPPacketSerial;