Update README.md

README.md

@@ -1,20 +1,172 @@
-Jetson Nano system monitor.
+# System monitoring
 
-Simple service that monitors system resource and shutdowns the system
+A simple service that monitors and collects information on system resource such as battery, temperature, memory, CPU, and network usage.
-when the battery is low
+The service can be used as backend for applications that need to consult system status.
 
-This service require the ADS1115 is connected to the
+`Sysmond` monitor ressource available on the system via the user space **sysfs interface**.
-Nano and is handled by the ads1015 linux driver
 
-The battery voltage value is available on user space as the content of
+The service logs all system information to application using a classic file-based interface, it can be configured to log system information to:
+* Regular text file (such as log file)
+* Name pipe (FIFO), the name pipe file should be previously created by application
+* STDOUT
+* UNIX socket domain, as with name pipe, the socket file must be previously created by application
+
+Additionally, if configured correctly, the service can monitor the system battery and automatically shutdown the system when the battery is below a configured threshold
+
+## Build and install
+The build process is done using autotool
 
 ```sh
-cat /sys/class/hwmon/hwmon2/device/in3_input
+libtoolize
+aclocal
+autoconf
+automake --add-missing
+# build
+make
+#install
+make install
 ```
 
-Statistic information that the daemon outputs:
+## Configuration
-- Battery
+
-- CPU usage
+The default configuration file can be found in `/etc/sysmond.conf`.
-- Memory usage
+Specific configuration file can be passed to the service using the `-f` option.
-- CPU/GPU temperature
+
-- Network trafic
+```sh
+sysmond -f /path/to/your/sysmond.conf
+```
+### Battery monitoring configuration
+
+The battery monitoring feature is helpful for battery-powered systems such as robotic systems.
+On these systems, battery voltage reading is performed with the help of an ADC sensor (such as ADS1115).
+As the service communicate with the system hardware via the **sysfs interface**, in order to provide input
+to `sysmond`, these ADCs sensor should accessible in user space via this interface. Usually, this is handled
+by the device dirver.
+
+For example, an `ADS1115` linux driver will expose its ADC channel inputs in user space at
+`/sys/class/hwmon/hwmon0/device/*`, if the battery is connected to the chanel 3 of the ADC sensor,
+the battery voltage can be easily read with a simple `cat` command:
+
+```sh
+cat sys/class/hwmon/hwmon0/device/in3_input
+# value in mV, example 4.1V
+4120 
+```
+This kind of file need to be passed to `sysmond` configuration. The following configuration availabe
+
+```ini
+# Max usable battery voltage
+battery_max_voltage = 12600
+
+# Min usable battery votage
+battery_min_voltage = 10000
+
+# Below this voltage, the battery is unusable and is damaged
+battery_cutoff_votalge = 9000
+
+# if voltage divider is used, the R1+R2/ R2 ratio shoud be set to `battery_divide_ratio`, otherwise `1.0`
+battery_divide_ratio = 3.36
+
+# Battery input file. If this configuration is empty, the battery monitoring feature is disabled
+battery_input = /sys/class/hwmon/hwmon2/device/in3_input
+
+# When battery is low the system will be shutdown after n count down
+power_off_count_down = 10
+
+# the system will bet shutdown if the battery voltage percent is below this value after `power_off_count_down` times
+power_off_percent = 3
+```
+
+Based on these configuration, `sysmond` can approximate the battery volage percent, it is also able to protect the battery by
+powering off the system when the batery percent bellow the configured value.
+
+### CPU, memory and storage usage configuration
+
+```sh
+# number of cpu cores to monitor, this value shoud be equal or less than the actual number of CPU cores in the system
+# CPU informations are fetched from /proc/stat
+cpu_core_number = 4
+
+# memory informations are automatically fetch from /proc/meminfo, no configuration needed
+
+# The mount point of the storage should be monitored
+disk_mount_point = /
+```
+
+### Temperature configuration
+
+```sh
+# System temperature informations can be found in /sys/devices/virtual/thermal/*
+# CPU temperature
+cpu_temperature_input=/sys/devices/virtual/thermal/thermal_zone1/temp
+
+# GPU temperature
+gpu_temperature_input=/sys/devices/virtual/thermal/thermal_zone2/temp
+```
+
+### Network monitoring configuration
+
+```sh
+# List of network interface to monitor
+network_interfaces = wlan0,eth0
+```
+
+### Other configurations
+
+```sh
+# Sampling period in ms, example: 2Hz (2 samples per second) should be
+sample_period = 500
+
+# Output system info to file
+# The output file may be: stdout, a regular file or name pipe, or a unix domain socket
+
+# To print JSON data records to stdout use
+data_file_out = stdout
+
+# To send data via unix domain socket use
+data_file_out = sock:/path/to/socket/file
+
+# regular file or name pipe
+data_file_out = /var/sysmond.log
+```
+
+## Output data format
+System informations are outputed in JSON format, example:
+
+```json
+{
+	"stamp_sec": 1612363252,
+	"stamp_usec": 890264,
+	"battery": 0.000,
+	"battery_percent": 0.000,
+	"battery_max_voltage": 12600,
+	"battery_min_voltage": 10000,
+	"cpu_temp": 52582,
+	"gpu_temp": 0,
+	"cpu_usages": [1.500, 2.000, 0.000, 2.000, 2.000],
+	"mem_total": 1891540,
+	"mem_free": 62780,
+	"mem_used": 729076,
+	"mem_buff_cache": 1099684,
+	"mem_available": 1360044,
+	"mem_swap_total": 0,
+	"mem_swap_free": 0,
+	"disk_total": 877448515584,
+	"disk_free": 876156772352,
+	"net": [{
+		"name": "eth0",
+		"rx": 1529461109,
+		"tx": 1704797921,
+		"rx_rate": 132.000,
+		"tx_rate": 1244.000
+	}]
+}
+```
+
+Note:
+* Battery is in mV
+* Temperature in is: Celsius\*1000
+* Memory in KB
+* Disk is in: bytes
+* Network rate Kb/s
+