From 44546111823b62525bb4c756ec53fbf5783c37b6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kry=C5=A1tof=20=C4=8Cern=C3=BD?= Date: Wed, 10 Apr 2024 14:00:42 +0200 Subject: [PATCH] Readability improvements (#140) --- docs/apis/bulk.md | 4 +-- docs/apis/json.md | 4 +-- docs/apis/rest.md | 4 +-- docs/apis/rpc.md | 2 +- docs/apis/webhook.md | 6 ++-- docs/apis/websocket.md | 4 +-- docs/configs/evok_configuration.md | 48 ++++++++++++++---------------- 7 files changed, 34 insertions(+), 38 deletions(-) diff --git a/docs/apis/bulk.md b/docs/apis/bulk.md index fe99046..e7596f4 100644 --- a/docs/apis/bulk.md +++ b/docs/apis/bulk.md @@ -1,10 +1,10 @@ # Evok Bulk API -The Bulk API is designed to provide an efficient way for clients to update, create or delete large amounts of data. This protocol support multiple write in one request. It is suitable for automated requests thanks JSON protocol, which is better machine-processed. +The Bulk API is designed to provide an efficient way for clients to update, create or delete large amounts of data. This protocol supports multiple writes in one request, but it is suitable for automated requests thanks JSON protocol, which is easily machine-processed. ## Examples -For python examples you need installed 'requests' package. You can install it with this command: `pip3 install requests`. +For python examples you need installed `requests` package. You can install it with this command: `pip3 install requests`. ### Setting DOs to HIGH diff --git a/docs/apis/json.md b/docs/apis/json.md index 3493506..b3f3430 100644 --- a/docs/apis/json.md +++ b/docs/apis/json.md @@ -1,10 +1,10 @@ # Evok JSON API -The JSON API provides a simple interface for sending and receiving data in a stateless, cacheable communications. This protocol do not support multiple write in one request. It is suitable for automated requests thanks JSON protocol, which is better machine-processed. +The JSON API provides a simple interface for sending and receiving data in a stateless, cacheable communications. This protocol does not support multiple writes in one request, but it is suitable for automated requests thanks to JSON protocol, which is easily machine-processed. ## Examples -For python examples you need installed 'requests' package. You can install it with this command: `pip3 install requests`. +For python examples you need installed `requests` package. You can install it with this command: `pip3 install requests`. ### Reading DI diff --git a/docs/apis/rest.md b/docs/apis/rest.md index b44b041..60f9a64 100644 --- a/docs/apis/rest.md +++ b/docs/apis/rest.md @@ -1,10 +1,10 @@ # Evok REST API -The REST API provides a simple interface for sending and receiving data in a stateless, cacheable communications. This protocol do not support multiple write in one request. It is suitable for hand-make requests. +The REST API provides a simple interface for sending and receiving data in a stateless, cacheable communications. This protocol does not support multiple writes in one request, thus it is suitable mainly for hand-made requests. ## Examples -For python examples you need installed 'requests' package. You can install it with this command: `pip3 install requests`. +For python examples you need installed `requests` package. You can install it with this command: `pip3 install requests`. ### Reading DI diff --git a/docs/apis/rpc.md b/docs/apis/rpc.md index 94b45b8..5459a0a 100644 --- a/docs/apis/rpc.md +++ b/docs/apis/rpc.md @@ -4,7 +4,7 @@ The RPC (Remote Procedure Call) API is used for invoking procedures, functions o ## Examples -For python examples you need installed 'requests' package. You can install it with this command: `pip3 install requests`. +For python examples you need installed `requests` package. You can install it with this command: `pip3 install requests`. ### Reading DI diff --git a/docs/apis/webhook.md b/docs/apis/webhook.md index b420315..34743fe 100644 --- a/docs/apis/webhook.md +++ b/docs/apis/webhook.md @@ -1,10 +1,10 @@ # Evok Webhook API -The Webhook API provides a mechanism for pushing real-time updates to clients. Evok sends the changes to the specified hostname and port. A list of reflected devices can be defined. It is suitable for collecting information about the running of the application. +The Webhook API provides a mechanism for pushing real-time updates to clients. Evok sends the changes to the specified hostname and port. A list of reflected devices can be defined. It is suitable for collecting information about the running application. ## Examples -For python examples you need installed 'flask' package. You can install it with this command: `pip3 install flask`. +For python examples you need installed `flask` package. You can install it with this command: `pip3 install flask`. ### Creating simple Webhook server @@ -40,7 +40,7 @@ For more information see [Evok configuration](../configs/evok_configuration.md). !!! note - After you change configuration you must restart the Evok with the command `systemctl restart evok`. + After you change configuration, you have to restart the Evok with the command `systemctl restart evok`. ```bash title="Output" * Serving Flask app 'server' diff --git a/docs/apis/websocket.md b/docs/apis/websocket.md index 69561ef..937d94e 100644 --- a/docs/apis/websocket.md +++ b/docs/apis/websocket.md @@ -1,12 +1,12 @@ # Evok WebSocket API -The WebSocket API allows for two-way communication between the client and server over an open connection. Evok sends changes to every connected client. A list of reflected devices can be defined. It is suitable if you need to immediately react to events in your application. +The WebSocket API allows for two-way communication between the client and the server over an open connection. Evok sends changes to every connected client. A list of reflected devices can be defined. It is suitable for cases, where you need to immediately react to events in your application. WIP ## Examples -For python examples you need installed 'websocket-client' package. You can install it with this command: `pip3 install websocket-client`. +For python examples you need installed `websocket-client` package. You can install it with this command: `pip3 install websocket-client`. ### Listening on websocket without filter diff --git a/docs/configs/evok_configuration.md b/docs/configs/evok_configuration.md index d4544a0..56df8d5 100644 --- a/docs/configs/evok_configuration.md +++ b/docs/configs/evok_configuration.md @@ -15,24 +15,19 @@ In this section you can configure address and port for APIs listening. This sett !!! info - More detailed settings of individual protocols can be found in separate sections. + More detailed settings of individual protocols can be found in their separate section. ### Websocket -- enabled - to enable/disable websocket API - - options: true / false -- all_filtered - 'all' WebSocket requests will be subject to the filtering set by 'filter' - - Options: true / false +- `enabled` - enabling/disabling websocket API (`true` / `false`) +- `all_filtered` - all WebSocket requests will be subject to the filtering set by 'filter' (`true` / `false`) ### Webhook -- enabled - to enable/disable webhook notifications - - Options: true / false -- address - address (with port) to which notifications should be sent -- device_mask - - Address (with port) to which notifications should be sent - - List of device types to notify on (written as a JSON list) -- complex_events - Evok will send POST requests with the same data as WebSocket, rather than an empty GET request +- `enabled` - enabling/disabling webhook notifications (`true` / `false`) +- `address` - address (with port) to which notifications should be sent +- `device_mask` - list of devices to notify on (written as a JSON list, same format as `address`) +- `complex_events` - Evok will send POST requests with the same data as WebSocket, rather than an empty GET request ## Hardware configuration @@ -50,24 +45,27 @@ comm_channels: scan_frequency: 50 ``` -- : Your choice, but can not have duplicates! -- : - - MODBUSTCP (specific settings: [hostname, port]) - - MODBUSRTU (specific settings: [port, boudrate, parity]) -- : Under this name, the device will be available in the API. Can not have duplicates! -- : +- **: Your choice, but has to be unique +- ** options: + - `MODBUSTCP` + - `hostname` - hostname of the Modbus server + - `port` - port of the Modbus server + - `MODBUSRTU` + - `port` - path to the Modbus device + - `boudrate` - baudrate of the Modbus device + - `parity` - parity of the Modbus device (`N` / `E` / `O`) +- **: the device will be available in the API under this name. Has to be unique. +- **: - Defines a modbus register map. - Source is located in '.yaml' files in '/etc/evok/hw_definitions'. - examples: xS51, xS11, - For more information see [hw_definitions](./hw_definitions.md). -- : Address of the modbus device. -- scan_frequency: - - An optional parameter that determines how often values are read from the device. - - Default value is 50. +- **: Address of the modbus device. +- `scan_frequency` - an optional parameter that determines how often values are read from the device (Default value is 50). ### Examples -Every example must be in section 'comm_channels'. +Every example must be in section `comm_channels`. #### Define xS51 on /dev/ttyNS0 @@ -104,9 +102,7 @@ If the Debian package `unipi-os-configurator` is installed, Evok can automatical /opt/unipi/tools/os-configurator -f ``` -Autogen example: - -```yaml +```yaml title="Autogen example" comm_channels: LOCAL_TCP: type: MODBUSTCP