Merge pull request #16 from bringauto/jan_kubalek/documentation_update

Documentation updated to reflect key points of Fleet Protocol

Author: koudis

.gitignore

@@ -1,4 +1,3 @@
-_tmp/
-_build/
+_*
 cmake-build-*
 .idea

README.md

@@ -1,47 +1,60 @@
 # Fleet Protocol
 
-Fleet Protocol is a communication protocol developed by BringAuto to allow simple and reliable communication between
-multiple devices and cloud infrastructure.
-**Complete protocol documentation will be released soon**. Protocol consists of three parts:
+Fleet Protocol is a communication technology developed by BringAuto to allow for **simple and reliable** communication between
+devices deployed in an **internet-connection-unstable** environment and cloud infrastructure.
 
-* internal client - specific part of device that communicates with module gateway
-* module gateway:
-    - internal server - communicates with internal client
-    - aggregator - aggregates status messages
-    - external client - communicates with external server
-* external server - communicates with server infrastructure that gives user the ability to control devices
+Protocol consists of three parts:
+
+* Internal Client (Remote) - part of a device which communicates with a Module Gateway
+* Module Gateway (Remote):
+    - internal server - communicates with internal clients
+    - aggregator - aggregates status messages, gathers and aggragates messages in case of connection outage, ...
+    - external client - communicates with an External Server
+* External Server (Cloud) - deployed as part of the cloud infrastructure. It provides status messages and can be used to control devices by command messages.
 
 ## Communication protocol
 
-We use [ProtoBuf] library for message format (version [Protobuf version]) and serialization/deserialization - protocol
+We use the [ProtoBuf] library for message format (version [Protobuf version]) and serialization/deserialization - protocol
 specification
-can be found in protobuff folder.
+can be found in protobuf folder.
 
-Each message must be prefixed with four bytes long (uint32_t data type) header which holds
-information about size of the ProtoBuf message.
+Each message must be prefixed with a four bytes long (uint32_t data type) header, which holds
+information about the size of the ProtoBuf message.
 
-To read more about the system architecture look at Fleet Protocol v2 documentation:
+To read more about the system architecture, check the Fleet Protocol v2 documentation:
 
-- [Summary]
+- [Summary] - overall high-level summary
 - [Fleet Protocol Requirements]
 - [Internal Client]
 - [Module Gateway]
 - [External Server]
-- [Modules]
+- [Modules] - list of implemented modules
 - [Message Structure]
 - [Internal Client design]
 - [Module Gateway design]
 - [External Server design]
+
+## HTTP Interface
+
+The Fleet Protocol HTTP API represents the protocol in the form of an HTTP API.
+
+A Fleet Protocol Module can use the HTTP API to provide its statuses and retrieve its commands
+through a simple and understandable REST API for easy integration with other services.
+
+Fleet Protocol HTTP API is a standalone project and is not part of the Fleet Protocol v2 core specification.
+
 - [HTTP API]
+- [HTTP API C++ Client]
+- [HTTP API Python3 Client]
 - [HTTP API Wait Mechanism]
 
-### Protocol messages
+## Protocol messages
 
-Messages are described by ProtoBuff v3.
+Messages are described by ProtoBuf v3.
 
-If the message filed is not mandatory then it's marked as OPTIONAL by "OPTIONAL"
+If a message field is not mandatory, then it's marked as OPTIONAL by "OPTIONAL"
 as the last comment in documentation for the given field.
-Optional fields has defaults as described in [ProtoBuf] v3 doc.
+Optional fields have defaults as described in the [ProtoBuf] v3 doc.
 
 ## Repo structure
 
@@ -57,7 +70,7 @@ Header files of interfaces
 
 ### Protobuf
 
-Protobuf compiled and non-compiled files
+Compiled and non-compiled protobuf files
 
 ## Usage
 
@@ -67,7 +80,7 @@ Protobuf compiled and non-compiled files
 
 ### Installation
 
-To install the library, first configure the project with CMake option BRINGAUTO_INSTALL=ON and BRINGAUTO_PACKAGE=ON and then install it.
+To install the library, first configure the project with the CMake option BRINGAUTO_INSTALL=ON and BRINGAUTO_PACKAGE=ON, and then install it.
 
 ```bash
 mkdir _build && cd _build
@@ -95,7 +108,7 @@ FIND_PACKAGE(fleet-protocol-interface REQUIRED)
 TARGET_LINK_LIBRARIES(<target> PUBLIC fleet-protocol-interface::fleet-protocol-interface)
 ```
 
-This will link all interfaces. If you want to link only specific interface, use the interfaces from the list below:
+This will link all interfaces. If you want to only link a specific interface, chose from the interfaces listed below:
 
 * fleet-protocol-interface::common-headers-interface
 * fleet-protocol-interface::internal-client-interface
@@ -136,3 +149,7 @@ This will link all interfaces. If you want to link only specific interface, use
 [HTTP API]: https://ref.bringautofleet.com/r/protocol/http-api/1.0.0/http-api
 
 [HTTP API Wait Mechanism]: https://ref.bringautofleet.com/r/protocol/http-api/1.0.0/wait-mechanism
+
+[HTTP API C++ Client]: https://github.com/bringauto/fleet-protocol-http-client-cxx
+
+[HTTP API Python3 Client]: https://github.com/bringauto/fleet-protocol-http-client-python