@@ -18,6 +18,8 @@ and stream an image to the installer, querying then for the status
and the final result. The API is at the moment very simple, but it can
easy be extended in the future if new use cases will arise.
+.. _install_api:
+
API Description
===============
@@ -83,3 +85,177 @@ The terminated call-back is called when SWUpdate has finished with the result
of the upgrade.
Example about using this library is in the examples/client directory.
+
+
+API to the integrated Webserver
+===============================
+
+The integrated Webserver provides REST resources to push a SWU package and to get inform about the update process.
+This API is based on HTTP standards. There are to kind of interface:
+
+- Install API to push a SWU and to restart the device after update.
+- A WebSocket interface to send the status of the update process.
+
+Install API
+-----------
+
+::
+
+ POST /upload
+
+This initiates an update: the initiator sends the request and start to stream the SWU in the same
+way as described in :ref:`install_api`.
+
+Restart API
+-----------
+
+::
+
+ POST /restart
+
+If configured (see post update command), this request will restart the device.
+
+
+WebSocket API
+-------------
+
+The integrated Webserver exposes a WebSocket API. The WebSocket protocol specification defines ws (WebSocket) and wss (WebSocket Secure) as two new uniform resource identifier (URI) schemes that are used for unencrypted and encrypted con
+nections, respectively and both of them are supported by SWUpdate.
+A WebSocket provides full-duplex communication but it is used in SWUpdate to send events to an external host after
+each change in the update process. The Webserver sends JSON formatted responses as results of internal events.
+
+The response contains the field type, that defines which event is sent.
+
+.. table:: Event Type
+
+ +-----------+----------------------------------------------------------------+
+ | type | Description of event |
+ +===========+================================================================+
+ | status | Event sent when SWUpdate's internal state changes |
+ +-----------+----------------------------------------------------------------+
+ | source | Event to inform from which interface an update is received |
+ +-----------+----------------------------------------------------------------+
+ | info | Event with custom message to be passed to an external process |
+ +-----------+----------------------------------------------------------------+
+ | message | Event that contains the error message in case of error |
+ +-----------+----------------------------------------------------------------+
+ | step | Event to inform about the running update |
+ +-----------+----------------------------------------------------------------+
+
+
+
+Status Change Event
+~~~~~~~~~~~~~~~~~~~
+
+This event is sent when the internal SWUpdate status change. Following status are supported:
+
+::
+
+ IDLE
+ START
+ RUN
+ SUCCESS
+
+
+Example:
+
+::
+
+ {
+ "type": "status",
+ "status": "SUCCESS"
+ }
+
+Source Event
+------------
+
+This event informs from which interface a SWU is loaded.
+
+::
+
+ {
+ "type": "source",
+ "source": "WEBSERVER"
+ }
+
+The field `source` can have one of the following values:
+
+::
+
+ UNKNOWN
+ WEBSERVER
+ SURICATTA
+ DOWNLOADER
+ LOCAL
+
+Info Event
+------------
+
+This event forwards all internal logs sent with level=INFO.
+
+::
+
+ {
+ "type": "info",
+ "source": < text message >
+ }
+
+Message Event
+-------------
+
+This event contains the error message in case of failure.
+
+
+.. table:: Fields for message event
+
+ +-----------+----------------------------------------------------------------+
+ | name | Description |
+ +===========+================================================================+
+ | status | "message" |
+ +-----------+----------------------------------------------------------------+
+ | level | "3" in case of error, "6" as info |
+ +-----------+----------------------------------------------------------------+
+ | text | Message associated to the event |
+ +-----------+----------------------------------------------------------------+
+
+Example:
+
+::
+
+ {
+ "type": "message",
+ "level": "3",
+ "text" : "[ERROR] : SWUPDATE failed [0] ERROR core/cpio_utils.c : ",
+ }
+
+Step event
+----------
+
+This event contains which is the current step running and which percentage of this step is currently installed.
+
+.. table:: Fields for step event
+
+ +-----------+----------------------------------------------------------------+
+ | name | Description |
+ +===========+================================================================+
+ | number | integer: total number of steps N for this update |
+ +-----------+----------------------------------------------------------------+
+ | step | running step in range [1..N] |
+ +-----------+----------------------------------------------------------------+
+ | name | filename of artefact to be installed |
+ +-----------+----------------------------------------------------------------+
+ | percent | percentage of the running step |
+ +-----------+----------------------------------------------------------------+
+
+Example:
+
+::
+
+ {
+ "type": "step",
+ "number": "7",
+ "step": "2",
+ "name": "rootfs.ext4.gz",
+ "percent": "18"
+ }
+
Describe the API with the integrated Webserver. Signed-off-by: Stefano Babic <sbabic@denx.de> --- doc/source/swupdate-ipc.rst | 176 ++++++++++++++++++++++++++++++++++++ 1 file changed, 176 insertions(+)