docs: even more on installation and usage

README.md

@@ -4,24 +4,41 @@ Monitors a Raspberry Pi [UART](https://en.wikipedia.org/wiki/Universal_asynchron
 serial):
 
 - Combines the stream of received bytes into single-line messages.
-- Uses configurable regular expressions to determine a log level.
+- Uses [configurable](./config-example-ttn.js) regular expressions to determine a log level.
 - Uses the log level to save the single-line messages to rotating log files, each line prefixed with a timestamp.
 - Optionally sends notifications to Slack and/or Telegram for lines with some minimum log level, or when the UART has
   been inactive for some configurable time.
 
 This is not intended to be a production-ready monitoring mechanism, if only as it has no fallback for losing its
 internet connection.
 
+## Contents
+
+- [Installation](#installation)
+- [Setting up the Raspberry Pi's UART](#setting-up-the-raspberry-pis-uart)
+- [Configuration](#configuration)
+  - [Creating `config.js`](#creating-configjs)
+  - [Configuring Slack (optional)](#configuring-slack-optional)
+  - [Configuring Telegram (optional)](#configuring-telegram-optional)
+- [Using the log files](#using-the-log-files)
+  - [Using `tail`](#using-tail)
+  - [Reading the rotated gzip'd files](#reading-the-rotated-gzipd-files)
+  - [Cleaning the resulting log files](#cleaning-the-resulting-log-files)
+- [Alternatives](#alternatives)
+- [Thanks!](#thanks)
 
 ## Installation
 
-A modern Raspberry Pi includes [Node.js](https://nodejs.org/) and its package manager NPM. This has been tested on a
-Pi 3 with Node.js 6.9.4 and NPM 3.10.10; when in doubt run `node --version` and `npm --version`.
+A modern Raspberry Pi probably includes [Node.js](https://nodejs.org/) and its package manager NPM. This has been tested
+on a Pi 3 running Raspbian Jessie with Node.js 6.9.4 and NPM 3.10.10; when in doubt run `node --version` and
+`npm --version`.
 
+- Run `git clone https://github.com/avbentem/raspi-uart-monitor.git`
+- Run `cd raspi-uart-monitor`
 - Run `npm install` to download all dependencies.
 - Create a configuration file; see [below](#configuration).
-- Set up your Pi's UART (see [below](#setting-up-the-raspberry-pis-uart)) and connect to whatever you want to monitor.
-- Test with `node index.js` (stop with Ctrl+C).
+- Set up your Pi's UART and connect it to whatever you want to monitor; see [below](#setting-up-the-raspberry-pis-uart).
+- Test with `node index.js` (stop by pressing Ctrl+C).
 
 To start the monitor on system boot, you could use [PM2](https://pm2.keymetrics.io/):
 
@@ -67,6 +84,8 @@ To start the monitor on system boot, you could use [PM2](https://pm2.keymetrics.
 
 ## Configuration
 
+### Creating `config.js`
+
 Copy [`config-example-ttn.js`](./config-example-ttn.js) into a new file `config.js` and adjust as needed.
 
 Restart the monitor whenever changing the configuration; like when using PM2: `pm2 restart uart-monitor`
@@ -75,14 +94,15 @@ Restart the monitor whenever changing the configuration; like when using PM2: `p
 
 To post messages to Slack, an App must be created:
 
-- Go to [slack.com/create](https://slack.com/create) if you want to register a new Slack workspace.
+- Go to [slack.com/create](https://slack.com/create) if you want to register a new Slack workspace. (As Slack only
+  preserves about 10,000 messages for free accounts, adding a bot to an existing workspace might get its history purged
+  much sooner than expected!)
 - In your (new) workspace, add a channel for the messages. (A dedicated channel allows for custom notifications.)
 - Go to [api.slack.com/apps/new](https://api.slack.com/apps/new) to create a new App.
 - After creating the App, in "Features", "Incoming Webhooks": enable "Activate Incoming Webhooks" and click 
   "Add New Webhook to Workspace". Select a channel and authorize it. Copy the URL to `config.json`.
 - It seems the token is not currently used, but if you want to have a complete configuration: from "Features",
   "OAuth & Permissions" copy the token to `config.json`.
- 
 
 ### Configuring Telegram (optional)
 
@@ -97,15 +117,45 @@ To post messages to Telegram, a bot is used. See [the official documentation](ht
 - Invite your new bot to the group.
 
 
-## Cleaning the resulting log files
+## Using the log files
+
+### Using `tail`
+
+This uses the Winston logger's [winston-daily-rotate-file](https://github.com/winstonjs/winston-daily-rotate-file),
+which works great but is [not very tail-friendly](https://github.com/winstonjs/winston-daily-rotate-file/issues/23):
+whenever the files are rotated, the current file gets a new name too. Consider using some external logrotate if
+that's an issue.
+
+### Reading the rotated gzip'd files
+
+By default, a Raspbian's installation of `vi` might not recognize compressed files. A simple upgrade helps:
+
+```bash
+sudo apt-get update
+sudo apt-get install vim
+```
+
+...after which `vi -R uart-monitor-debug-20180301.log.gz` just works. (Note that `grep` already works fine for
+compressed logs.)
+
+### Cleaning the resulting log files
 
 The monitor logs a line `[monitor] Starting UART monitor`. One can easily remove those using something like:
 
 ```text
 cat uart-monitor-debug-20180302.log | grep -v '\[monitor\]' > clean.log
 ```
 
-Alternatively, just remove that line from [`index.js`](./index.js).
+Alternatively, just remove the creation of that that line from [`index.js`](./index.js).
+
+
+## Alternatives
+
+If you just want to add a timestamp to the logging and show it on the screen and save all to a file as well, like when
+using [PlatformIO](https://platformio.org/), then all you need is:
+
+```LOG="serial-`date +'%Y%m%d-%H%M%S'`.log"; pio serialports monitor --raw -b 115200 | while read l; do echo "[`date +'%F %T'`] $l" | tee -a $LOG; done```
+
 
 ## Thanks!
 

index.js

@@ -21,7 +21,7 @@ logService.warn('[monitor] Starting UART monitor');
 const notificationService = new NotificationService(config.notifications);
 notificationService.warn('Starting UART monitor');
 
-// The watchdog only sends notifications to Telegram and/or Slack, if configured
+// The watchdog only sends notifications to Telegram and/or Slack (if configured), not to the log files
 const watchdogService = new WatchdogService(config.watchdog, notificationService);
 
 /**