@@ -123,7 +123,7 @@ so that the new implementation becomes selectable in SWUpdate's
configuration. In the simplest case, adding an option like the following
one for hawkBit into the ``menu "Server"`` section is sufficient.
-::
+.. code:: bash
config SURICATTA_HAWKBIT
bool "hawkBit support"
@@ -141,8 +141,126 @@ the SWUpdate binary, e.g., for the hawkBit example implementation, the
following lines add ``server_hawkbit.o`` to the resulting SWUpdate binary
if ``SURICATTA_HAWKBIT`` was selected while configuring SWUpdate.
-::
+.. code:: bash
ifneq ($(CONFIG_SURICATTA_HAWKBIT),)
lib-$(CONFIG_SURICATTA) += server_hawkbit.o
endif
+
+
+Support for general purpose HTTP server
+---------------------------------------
+
+This is a very simple backend that uses standard HTTP response codes to signal if
+an update is available. There are closed source backends implementing this interface,
+but because the interface is very simple interface, this server type is also suitable
+for implementing an own backend server.
+
+The API consists of a GET with Query parameters to inform the server about the installed version.
+The query string has the format:
+
+::
+
+ http(s)://<base URL>?param1=val1¶m2=value2...
+
+As examples for parameters, the device can send its serial number, MAC address and the running version of the software.
+It is duty of the backend to interprete this - SWUpdate just takes them from the "identity" section of
+the configuration file and encodes the URL.
+
+The server answers with the following return codes:
+
++-----------+-------------+------------------------------------------------------------+
+| HTTP Code | Text | Description |
++===========+=============+============================================================+
+| 302 | Found | A new software is available at URL in the Location header |
++-----------+-------------+------------------------------------------------------------+
+| 400 | Bad Request | Some query parameters are missing or in wrong format |
++-----------+-------------+------------------------------------------------------------+
+| 403 | Forbidden | Client certificate not valid |
++-----------+-------------+------------------------------------------------------------+
+| 404 | Not found | No update is available for this device |
++-----------+-------------+------------------------------------------------------------+
+| 503 | Unavailable | An update is available but server can't handle another |
+| | | update process now. |
++-----------+-------------+------------------------------------------------------------+
+
+Server's answer can contain the following headers:
+
++---------------+--------+------------------------------------------------------------+
+| Header's name | Codes | Description |
++===============+========+============================================================+
+| Retry-after | 503 | Contains a number which tells the device how long to wait |
+| | | until ask the next time for updates. (Seconds) |
++---------------+--------+------------------------------------------------------------+
+| Content-MD5 | 302 | Contains the checksum of the update file which is available|
+| | | under the url of location header |
++---------------+--------+------------------------------------------------------------+
+| Location | 302 | URL where the update file can be downloaded. |
++---------------+--------+------------------------------------------------------------+
+
+The device can send logging data to the server. Any information is transmitted in a HTTP
+PUT request with the data as plain string in the message body. The Content-Type Header
+need to be set to text/plain.
+
+The URL for the logging can be set as separate URL in the configuration file or via
+--logurl command line parameter:
+
+The device sends data in a CSV format (Comma Separated Values). The format is:
+
+::
+
+ value1,value2,...
+
+The format can be specified in the configuration file. A *format* For each *event* can be set.
+The supported events are:
+
++---------------+------------------------------------------------------------+
+| Event | Description |
++===============+========+===================================================+
+| check | dummy. It could send an event each time the server is |
+| | polled. |
++---------------+------------------------------------------------------------+
+| started | A new software is found and SWUpdate starts to install it |
++---------------+------------------------------------------------------------+
+| success | A new software was successfully installed |
++---------------+------------------------------------------------------------+
+| fail | Failure by installing the new software |
++---------------+------------------------------------------------------------+
+
+The `general server` has an own section inside the configuration file. As example:
+
+::
+
+ gservice =
+ {
+ url = ....;
+ logurl = ;
+ logevent : (
+ {event = "check"; format="#2,date,fw,hw,sp"},
+ {event = "started"; format="#12,date,fw,hw,sp"},
+ {event = "success"; format="#13,date,fw,hw,sp"},
+ {event = "fail"; format="#14,date,fw,hw,sp"}
+ );
+ }
+
+
+`date` is a special field and it is interpreted as localtime in RFC 2822 format. Each
+Comma Separated field is looked up inside the `identify` section in the configuration
+file, and if a match is found the substitution occurs. In case of no match, the field
+is sent as it is. For example, if the identify section has the following values:
+
+
+::
+
+ identify : (
+ { name = "sp"; value = "333"; },
+ { name = "hw"; value = "ipse"; },
+ { name = "fw"; value = "1.0"; }
+ );
+
+
+with the events set as above, the formatted text in case of "success" will be:
+
+::
+
+ Formatted log: #13,Mon, 17 Sep 2018 10:55:18 CEST,1.0,ipse,333
This describe the simple protocol based on HTTP codes for the general HTTP backend server. Signed-off-by: Stefano Babic <sbabic@denx.de> --- doc/source/suricatta.rst | 122 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 120 insertions(+), 2 deletions(-)