From 4cf93cdc8975bd6f2e4761081370108b34a29f1f Mon Sep 17 00:00:00 2001
From: mj <mj370@protonmail.com>
Date: Fri, 26 Nov 2021 21:08:30 +0100
Subject: [PATCH] Added README.md for test folder

---
 tests/README.md       | 64 +++++++++++++++++++++++++++++++++++++++++++
 tests/query_device.py | 45 ++++++++++++++++++------------
 2 files changed, 91 insertions(+), 18 deletions(-)
 create mode 100644 tests/README.md

diff --git a/tests/README.md b/tests/README.md
new file mode 100644
index 0000000..ab33c3f
--- /dev/null
+++ b/tests/README.md
@@ -0,0 +1,64 @@
+# Test scripts
+
+Python scripts used for sensor reading, configuring and automated testing. All scripts assume that 485 converter device file is `/dev/rs485`.
+
+## User scripts
+
+Following scripts are meant to be used by user for sensor search, read and config (write).
+
+### `find_device.py`
+
+Search for device over all combinations of given baudrates and addresses. If no arguments are given, script tries all possible combinations (which takes really long time).
+
+Usage:
+
+```
+./find_device.py [ -a [{FIRST_ADDR-LAST_ADDR | ADDR} ...] ] [ -b [BAUD ...]]
+```
+
+Examples:
+
+```
+Complete search (slow!):
+	./find_device.py
+Look for devices 123,10,56 at baudrates 19200,115200:
+	./find_device.py -a 123 10 56 -b 19200 115200
+Look for devices 10-55 at baudrate 19200:
+	./find_device.py -a 10-55 -b 19200
+Look for device 1-10 and 55 at baudrate 115200:
+	./find_device.py -a 1-10 55 -b 115200
+Look for device 1-10 at all possible baudrates:
+	./find_device.py -a 1-10 55
+
+```
+
+### `query_device.py`
+
+Script for interaction with sensor. Allows reading from input register and read/write access to holding registers.
+
+Usage:
+
+```
+./query_device.py ADDR [BAUDRATE] [{read [REGISTER ...] | write VALUE REGISTER}]
+where:
+    - ADDR is Modbus address (use 0 for broadcast; note that only write can be broadcast)
+    - BAUDRATE is (optional) baud rate; default value is 19200
+    - action can be "read", "write" or can be omitted (defaults to "read all")
+    - REGISTER can be either human-friendly register name (e.g. "CO2") or register number (30001)
+    - read may have list of REGISTER arguments (combining both register numbers and names)
+    - VALUE is 16-bit integer in decimal format
+    - to get list of human-friendly names just read all registers from sensor (run script with address only)
+
+EXAMPLES
+
+Read all registers from sensor 247, default baud rate:
+    ./query_device.py 247
+Read only CO2 register from sensor 123, baudrate 4800:
+    ./query_device.py 123 4800 read CO2
+Read CO2, T_SHT4x and RH_SCD4x from sensor 222, default baudrate:
+    ./query_device.py 222 read CO2 T_SHT4x RH_SCD4x
+Turn LED off for sensor 247, baud 115200:
+    ./query_device.py 247 115200 write 0 LED_on_register
+Set brightness of all connected sensors to 50%:
+    ./query_device.py 0 write 50 LED_brightness_register
+```
diff --git a/tests/query_device.py b/tests/query_device.py
index 9bc1fef..601267c 100755
--- a/tests/query_device.py
+++ b/tests/query_device.py
@@ -2,25 +2,31 @@
 from sensor import Sensor
 from sys import argv,exit
 
-# query read input
-#       read holding
-#       write input/holding [REG]
-#
-#
-#
-# query_device.py ADDR [BAUDRATE] [{read [REGISTER] | write REGISTER}]
-#    where:
-#       - ADDR is MODBUS address. Special case is ADDR=0 (broadcast),
-#         for which you may write, but not read
-#       - BAUDRATE is baudrate (duh!), default value 19200
-#       - REGISTER is either register number (e.g. 30010 for input register CO2),
-#         or register name (e.g. CO2)
-#            - list of register names...
-#       - if only ADDR (and optionally BAUDRATE) is supplied, query all possible information from sensor
-#
-
 def print_help():
-    print("HEEEELP")
+    print( \
+f'''{argv[0]} ADDR [BAUDRATE] [{{read [REGISTER ...] | write VALUE REGISTER}}]
+where:
+    - ADDR is Modbus address (use 0 for broadcast; note that only write can be broadcast)
+    - BAUDRATE is (optional) baud rate; default value is 19200
+    - action can be "read", "write" or can be omitted (defaults to "read all")
+    - REGISTER can be either human-friendly register name (e.g. "CO2") or register number (30001)
+    - read may have list of REGISTER arguments (combining both register numbers and names)
+    - VALUE is 16-bit integer in decimal format
+    - to get list of human-friendly names just read all registers from sensor (run script with address only)
+
+EXAMPLES
+
+Read all registers from sensor 247, default baud rate:
+    {argv[0]} 247
+Read only CO2 register from sensor 123, baudrate 4800:
+    {argv[0]} 123 4800 read CO2
+Read CO2, T_SHT4x and RH_SCD4x from sensor 222, default baudrate:
+    {argv[0]} 222 read CO2 T_SHT4x RH_SCD4x
+Turn LED off for sensor 247, baud 115200:
+    {argv[0]} 247 115200 write 0 LED_on_register
+Set brightness of all connected sensors to 50%:
+    {argv[0]} 0 write 50 LED_brightness_register
+''')
 
 # default values
 DEFAULT_BAUDRATE = 19200
@@ -87,6 +93,9 @@ if action != 'write' and len(register_name) + len(register_number) == 0:
     input_registers = [ x for x in Sensor.input_register_offset.keys() ]
     holding_registers = [ x for x in Sensor.holding_register_offset.keys() ]
     register_name = input_registers + holding_registers
+if action != 'write' and addr == 0:
+    print(f'Cannot broadcast action "{action}"')
+    exit(-12)
     
 # Query device
 print('---- Query device ----')