Introduction of raw TCP rules

gitbook-docs/README.md

@@ -11,7 +11,7 @@ version.
 ## What is Signal K?
 
 **Signal K** is a modern and open data format for marine use. It is an Internet friendly standard built on standard web
-technologies, such as JSON and WebSockets. Signal K is Free and Open Source software. This document is licensed under
+technologies. Signal K is Free and Open Source software. This document is licensed under
 the Creative Commons [CC-BY-SA](https://creativecommons.org/licenses/by-sa/4.0/) license. All Signal K source code is
 licensed under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0). Signal K is developed in
 the open with help from the marine community. Your ideas and feedback are valuable and welcome.
@@ -48,7 +48,7 @@ understood by existing devices without the need for firmware upgrades.
 
 Signal K does not define the transport or wire protocol. Signal K messages are JSON text and can be sent over almost any
 transport layer. However, we do provide guidance on how to make an initial connection, handle negotiation,
-subscription, and disconnection for a given transport (e.g. TCP/IP or serial).
+subscription, and disconnection for a range of transports (e.g. TCP/IP or serial).
 
 Where possible we use well established standards like HTTPS, REST, WebSockets, MQTT, STOMP, etc. But within each method
 there are always many options in message addressing, formating, or transfer (GET, POST), etc.

gitbook-docs/SUMMARY.md

@@ -12,7 +12,7 @@
 * [API]()
   * [Ports, Urls and Versioning](urls_etc.md)
   * [REST API](rest_api.md)
-  * [Streaming WebSocket API](streaming_api.md)
+  * [Streaming API (TCP sockets and Websockets)](streaming_api.md)
   * [Discovery & Connection Establishment](connection.md)
   * [Subscription Protocol](subscription_protocol.md)
 * [Background and Design Rationale](design_notes.md)

gitbook-docs/connection.md

@@ -6,6 +6,7 @@ A Signal K server SHOULD advertise its services over mDNS/Bonjour. The server MU
 
 * `_signalk-http._tcp` for http API
 * `_signalk-ws._tcp` for WebSocket
+* `_signalk-tcp._tcp` for raw TCP socket
 * `_signalk-https._tcp` for HTTPS API
 * `_signalk-wss._tcp` for secure WebSocket
 
@@ -54,7 +55,8 @@ Using the information above a web client or http capable device can discover and
         "v1": {
             "version": "1.1.2",
             "signalk-http": "http://192.168.1.2/signalk/v1/api/",
-            "signalk-ws": "ws://192.168.1.2:34567/signalk/v1/stream"
+            "signalk-ws": "ws://192.168.1.2:34567/signalk/v1/stream",
+            "signalk-tcp": "tcp://192.168.1.2:3858"
         }
      }
  }

gitbook-docs/service_discovery.md

@@ -4,6 +4,7 @@ A Signal K server SHOULD advertise its services over mDNS/Bonjour. The server MU
 
 * `_signalk-http._tcp` for http API
 * `_signalk-ws._tcp` for WebSocket
+* `_signalk-tcp._tcp` for raw TCP socket
 * `_signalk-https._tcp` for HTTPS API
 * `_signalk-wss._tcp` for secure WebSocket
 

gitbook-docs/streaming_api.md

@@ -1,4 +1,4 @@
-#### Streaming WebSocket API: /signalk/v1/stream
+3 #### Streaming WebSocket API: /signalk/v1/stream
 
 Initiates a WebSocket connection that will start streaming the server's updates as Signal K delta messages. You can specify the contents of the stream by using a specific URL:
 
@@ -23,3 +23,15 @@ Upon connection a 'hello' message is sent as follows:
   "self": "123456789"
 }
 ```
+
+#### Streaming: TCP sockets
+
+A network node MAY stream signalk-delta over a TCP socket.
+
+When a hello or signalk-delta message is sent over a TCP socket:
+
+1. Each message MUST be terminated by a carriage return and new line (char(13) + char(10), '\r\n') sent immediatly after the final closing curly bracket (char(125), '}').
+2. The first character of each message SHOULD be the openning curly bracket (char(123), '{').
+3. The message SHOULD be sent with any unnessesary white space removed.
+
+Note on hardware implementation: The serial APIs for ethernet and wifi modules often close a TCP or UDP packet on receipt of a new line ( char(10) ). Please check the data sheet and ensure the new line character is still sent.

gitbook-docs/urls_etc.md

@@ -1,9 +1,8 @@
-#Ports, Urls and Versioning
+##Ports, Urls and Versioning
 
 ### Short Names
 
 - `self` refers to the current vessel. Normally used in `vessels.self...`.
-
 ### Ports
 
 The Signal K HTTP and WebSocket services SHOULD be found on the usual HTTP/S ports (80 or 443). The services SHOULD be
@@ -14,22 +13,17 @@ A Signal K server MAY offer Signal K over TCP or UDP, these services SHOULD be o
 If an alternate port is needed it SHOULD be an arbitrary high port in the range 49152–65535[[2]](#fn_2).
 
 ### URL Prefix
-
-The Signal K applications start from the `/signalk` root. This provides some protection against name collisions with
+aTihe Signal K applications start from the `/signalk` root. This provides some protection against name collisions with
 other applications on the same server. Therefore the Signal K entry point will always be found by loading
 `http(s)://«host»:«port»/signalk`.
 
 ### Versioning
 
 The version(s) of the Signal K API that a server supports SHALL be available as a JSON object available at `/signalk`:
-
 ```json
 {
-    "endpoints": {
-        "v1": {
-            "version": "1.1.2",
-            "signalk-http": "http://192.168.1.2/signalk/v1/api/",
-            "signalk-ws": "ws://192.168.1.2:34567/signalk/v1/stream"
+    "endpoints": {        "v1": {
+            "version": "1.1.2",            "signalk-http": "http://192.168.1.2/signalk/v1/api/",            "signalk-ws": "ws://192.168.1.2:34567/signalk/v1/stream"
         },
         "v3": {
             "version": "3.0",
@@ -69,9 +63,9 @@ If a server does not support some streaming options listed in here it must respo
 
 See [Subscription Protocol](subscription_protocol.html) for more details.
 
-##### Connection Hello
+#### Streaming Connection "Hello"
 
-Upon connection a 'hello' message is sent as follows:
+Before a node sends any signalk-delta messages over a Web Socket or TCP connection it MUST send a 'hello' message. The format of the 'hello' message is as follows:
 
 ```json
 {
@@ -80,3 +74,14 @@ Upon connection a 'hello' message is sent as follows:
   "self": "123456789"
 }
 ```
+
+"version" - The 'hello' message MUST contain a "version" property which MUST have a string value identifying the lowest version of signalk-delta that defines the format of the messages that will follow.
+
+"timestamp" - The 'hello' message SHOULD contain a "timestamp" property.
+
+1. The timestamp MUST have a string value representing the date and time at the node that sent the 'hello' message.
+2. The timestamp SHOULD be synchronised with UTC. UTC timestamps MUST end with a capital Z.
+3. If the timestamp is not synchronised with UTC then the receiving node SHOULD compare the timestamp with the time at the receiving node at which the 'hello' is received and use the delta to correct the timestamp of subsequent signalk-delta messages received from the sending node. If it can not perform this function it MUST delete the timestamp and treat the message as if it had no timestamp.
+
+"self" - The 'hello' massage MAY contain a "self" property which MUST have a string value that identifies the vessel the message pertains to.
+