Update README.

Author: bakercp

README.md

@@ -11,7 +11,7 @@ _PacketSerial_ is an small, efficient, library that allows [Arduinos](http://www
 
 ## Background
 
-_"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 carriage return `\r` and a line feed `\n`) before sending them.  This is what happens if you call and `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 5 bytes total. As a result the receiver won't just receive a byte for the number and two bytes for the carriage return and new line character. Instead it will receive a stream of 5 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 carriage return `\r` and a line feed `\n`) before sending them. This is what happens if you call and `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 5 bytes total. As a result the receiver won't just receive a byte for the number and two bytes for the carriage return and new line character. Instead it will receive a stream of 5 bytes:
 
 ```
 50 // ASCII '2'
@@ -21,7 +21,7 @@ _"Why do I need this?"_ you may ask. The truth is that you may not need it if yo
 10 // ASCII '\n'
 ```
 
-The receiver must then collect the 3 ASCII characters `{ '2', '5', '5' }`, combine them and convert them back into a single byte with a value of `255`. This process can get complicated when the user wants to send large quantities of structured data between the Arduino and a receiver.
+The receiver must then collect the 3 ASCII characters { '2', '5', '5' }, combine them and convert them back into a single byte with a value of `255`. This process can get complicated when the user wants to send large quantities of structured data between the Arduino and a receiver.
 
 One way to send a _packet_ of data without this library is to send each byte separated by a comma or space and terminate the sequence with a new line character. Thus, to send the value `255` and the value `10`, one might call:
 
@@ -46,7 +46,14 @@ The receiver will actually see a stream of 7 bytes:
 
 In this case, the receiver must then collect the ASCII characters, combine them, skip the delimiter (the comma in this case) and then process the packet when a new line is encountered. While effective, this method doesn't scale particularly well. Bytes with values larger than 9 are encoded as 2 bytes and bytes with values larger than 99 are encoded as 3 bytes, etc. If the user would like to send the number 4,294,967,295 (the maximum value of a 4 byte `unsigned long`), it would be encoded as 10 bytes. This means that there is an overhead of 6 extra bytes to transmit a 4 byte `unsigned long`.
 
-An alternative to ASCII encoding is to write the bytes directly to using the `Serial.write()` methods. These methods do not convert the byte values to ASCII. So if the user wants to send a single byte with the value of 255 and follow it with a new line character (i.e. `Serial.write(255); Serial.write('\n');`), the receiver will see a stream of 2 bytes:
+An alternative to ASCII encoding is to write the bytes directly to using the `Serial.write()` methods. These methods do not convert the byte values to ASCII. So if the user wants to send a single byte with the value of `255` and follow it with a new line character:
+
+```c++
+Serial.write(255);
+Serial.write('\n');
+```
+
+the receiver will see a stream of 2 bytes:
 
 ```
 255 // The value transmitted.
@@ -59,82 +66,139 @@ Another coding available in PacketSerial is [Serial Line Internet Protocol](http
 ## Use
 ### PacketSerial
 
-The `PacketSerial` class wraps the standard Arduino `Serial` class to automatically encode and decode byte packets. Thus users can still call methods on the `Serial` object (e.g. `Serial.write()`, the built in `serialEvent()` callback etc), but it is not recommended. Users are advised to let PacketSerial manage all Serial communication via the packet handler callback for incoming packets and the `send(const uint8_t* buffer, size_t size) const` method for outgoing packets. Mixing raw Serial calls with `PacketSerial` may lead to unexpected encoding and decoding results, as the endpoint will not know what data is encoded and what data is not.
+`PacketSerial` class wraps the Arduino `Stream` class to automatically encode and decode byte packets that are sent and received. Typically serial communication uses the default `Serial` object, which implements the `Stream` class. In most cases, `PacketSerial` should be given exclusive access to the serial `Stream` (e.g. for a default setup using `Serial`, users should avoid calling functions like `Serial.print()`, `Serial.write()`, etc directly). Data should be sent via the `send(const uint8_t* buffer, size_t size) const` method and received in a `PacketSerial` callback function (see below).
 
 ### Setup
+#### Basic
 
-For Arduino boards with more than one serial port, `PacketSerial` the desired serial port can be specified with the `begin` method, i.e.
+To use the default `Serial` object and the default communication settings (usually `SERIAL_8N1`), set up `PacketSerial` like this:
 
 ```c++
-void begin(unsigned long speed, uint8_t config, size_t port = 0)
+PacketSerial myPacketSerial;
+
+void setup()
+{
+    myPacketSerial.begin(9600);
+    myPacketSerial.setPacketHandler(&onPacketReceived);
+}
 ```
 
-Where:
+### Advanced
+
+For a non-default Serial connection, a class implementing the `Stream` interface should be configured and then set for the `PacketSerial` instance.
+
+#### Using A Non-Standard Serial Configuration
+
+PacketSerial myPacketSerial;
+
+```c++
+void setup()
+{
+    Serial.begin(300, SERIAL_7N1);
+    myPacketSerial.setStream(&Serial);
+    myPacketSerial.setPacketHandler(&onPacketReceived);
+}
+```
 
-| _Arduino_ Serial Port | _PacketSerial_ Port Number |
-| ------------- |:-------------:|
-| `Serial`      | 0           |
-| `Serial1`     | 1           |
-| `Serial2`     | 2           |
-| `Serial3`     | 3           |
+#### Using Secondary Serial Ports (e.g. Serial1, Serial2, etc)
 
-Alternatively, to use a software serial port or other pre-configured network stream you can use an alternate `begin` method, this time with only a `Stream*` as argument, e.g.:
 ```c++
-void begin(Stream* serial)
+PacketSerial myPacketSerial;
+
+void setup()
+{
+    Serial1.begin(9600);
+    myPacketSerial.setStream(&Serial1);
+    myPacketSerial.setPacketHandler(&onPacketReceived);
+}
 ```
 
-To set this up, you might do the following:
+#### Using SoftwareSerial
+
 ```c++
 PacketSerial myPacketSerial;
 SoftwareSerial mySoftwareSerial(10, 11);
 
-// In this case the serial port has to be initialized before passing it to PacketSerial.
-mySoftwareSerial.begin(38400);
-myPacketSerial.begin(&mySoftwareSerial);
+void setup()
+{
+    mySoftwareSerial.begin(38400);
+    myPacketSerial.setStream(&mySoftwareSerial);
+    myPacketSerial.setPacketHandler(&onPacketReceived);
+}
 ```
 
-On boards with multiple serial ports, this strategy can also be used to set up two Serial streams, one for packets and one for debug ASCII (see [this discussion](https://github.com/bakercp/PacketSerial/issues/10) for more).
+#### Other Streams
 
-To receive decoded packets, the user should register a packet callback. The packet callback should be placed in your main Arduino Sketch and should have a method that looks like this:
+Any class that correctly implements the `Stream` interface should work, which includes some network communication objects.
+
+### Loop
+
+In order to processing incoming serial packets, the user must call the `update()` method at the end of the `loop()` method.
 
 ```c++
-void onPacket(const uint8_t* buffer, size_t size)
+void loop()
 {
-    // Process your decoded incoming packet here.
+    // Your program here.
+
+
+    // Call update to receive, decode and process incoming packets.
+    myPacketSerial.update();
 }
+
 ```
 
-Your callback can have any name and should be registered in the `setup()` method like this:
+### Receiving Packets
+
+All packets are received via handler functions. A typical handler function would be registered in the `void setup()` function like:
 
 ```c++
-void setPacketHandler(PacketHandlerFunction onPacketFunction)
+PacketSerial myPacketSerial;
+
+void setup()
+{
+    myPacketSerial.begin(9600);
+    myPacketSerial.setPacketHandler(&onPacketReceived);
+}
 ```
 
-### Main Loop
+The `onPacketReceived` function can take two forms. The simplest looks like this:
 
-In order to processing incoming serial packets, the user must call the `update()` method at the end of the `loop()` method.
 
 ```c++
-void loop()
+void onPacketReceived(const uint8_t* buffer, size_t size)
 {
-    // Your program here.
+    // Process your decoded incoming packet here.
+}
+```
+
+For more advanced programs with multiple PacketSerial instances and a shared handler, it may be useful to know which PacketSerial instance received the packet. In this case you could define a callback like this:
 
-    serial.update();
+```c++
+void onPacketReceived(const void* sender, const uint8_t* buffer, size_t size)
+{
+    if (sender == &myPacketSerial)
+    {
+        // Do something with the packet from myPacketSerial.
+    }
+    else if (sender == &myOtherPacketSerial)
+    {
+        // Do something with the packet from myOtherPacketSerial.
+    }
 }
 
 ```
 
 ### Sending Packets
 
-To send packets call the `send()` method. The send method will take a packet (an array of bytes), encode it, transmit it and send the packet boundary marker (usually `0`). To send the values 255 and 10, one might do the following:
+To send packets call the `send()` method. The send method will take a packet (an array of bytes), encode it, transmit it and send the packet boundary marker. To send the values `255` and `10`, one might do the following:
 
 ```c++
 
 // Make an array.
-uint8_t myPacket[] { 255, 10 };
+uint8_t myPacket[2] = { 255, 10 };
 
 // Send the array.
-serial.send(myPacket, 2);
+myPacketSerial.send(myPacket, 2);
 ```
 
 ## Examples
@@ -151,5 +215,6 @@ See the included examples for further usage options.
 ## Changelog
 See [CHANGELOG.md](CHANGELOG.md)
 
+
 ## License
-See [LICENSE.md](LICENSE.md)
+See [LICENSE.md](LICENSE.md)