examples: Improve README by describing scripts

examples/README.md

@@ -3,21 +3,21 @@
 This directory contains a number of scripts to process the output of
 rtl_433 in various ways.  Some are truly examples; they worked for
 someone else and won't work for you but will help understanding.  Some
-are (or will be once enhanced) actually useful to a fairly broad set
-of people.
+are actually useful to a fairly broad set of people and are used in
+production.  Some of course are somewhere in the middle.
 
 It is likely that a use outside what has been contemplated will
 require writing new code, with some kind of filtering and
 transformation.
 
-Generally, python scripts should work with Python 2 or relatively
-recent Python 3.  (It is TBD to deprecate Python 2; it is not clear
-that anyone still cares.)
+Generally, python scripts should work with relatively recent Python 3.
+(While they might work with 2.7, no one is paying attention to that.)
 
 These scripts typically send data to some other system, store it in a
 database, or process it in some way.  Recall that rtl_433's philosophy
 is to just output received transmissions, with minimal processing and
-with no checking/correlation of adjacent repeated frames.
+with no checking/correlation of adjacent repeated frames.  These
+scripts bridge the gap between raw output and useful information.
 
 This directory has a strong bias to the use of JSON; the point of that
 encoding is that it is machine parseble and that's what we want to do.
@@ -54,6 +54,59 @@ With this, one can run `tcpdump -A -i lo0 udp and port 1433`
 (substitute your loopback interface) to watch the traffic.  One can
 also run multiple rtl_433 processes.
 
+# Orientation
+
+We attempt to categorize and describe the scripts in this directory.
+
+Home Assistant is abbreviated HA.
+
+## Production Scripts
+
+A production script could be installed as a program, if it also had a
+man page.  Many people should be able to use it without having to edit
+the source code.
+
+## Generally Usable Scripts
+
+A generally usable script will likely need minor tweaking.
+
+  - rtl_433_mqtt_relay.py: Send data via MQTT (e.g. to HA).
+  - rtl_433_mqtt_hass.py: Send HA autoconfiguration data, so that entities for the decoded sensors will automatically appear.
+
+## True Examples
+
+These are not likely to to be useful, except that reading them will
+lead to better understanding, and bits of code may be useful..  
+
+  - mqtt_rtl_433_test_client.py: Connect to broker and print data from rtl topics
+  - rtl_433_custom.php: Receive json syslog packets in php
+  - rtl_433_custom.py: Receive json syslog packets in python
+  - rtl_433_gps.py: Receive json data and also gpsd data 
+  - rtl_433_http_cmd.py: Custom hop controller example for rtl_433's HTTP cmd API
+  - rtl_433_http_cmd.sh: Custom hop controller example for rtl_433's HTTP cmd API
+  - rtl_433_http_events.py: Custom data handling example for rtl_433's HTTP (chunked) streaming API of JSON events
+  - rtl_433_http_stream.php: Short example of an TCP client written in PHP for rtl_433
+  - rtl_433_http_stream.py: Custom data handling example for rtl_433's HTTP (line) streaming API of JSON events
+  - rtl_433_http_ws.py: Custom data handling example for rtl_433's HTTP WebSocket API of JSON events
+
+## Not Understood
+
+  - sigrok-conv.sh: print a hint
+  - sigrok-open.sh: print a hint
+
+## Uncategorized
+
+These scripts are in the directory but have not been sorted and described.
+
+  - rtl_433_graphite_relay.py: Send data to graphite
+  - rtl_433_influxdb_relay.py: Send data to influxdb
+  - rtl_433_prometheus_relay.py: Send data to prometheus
+  - rtl_433_rrd_relay.py: Send data to rrd
+  - rtl_433_statsd_relay.py: Send data to statsd
+  - rtl_433_collectd_pipe.py: Send data to collected
+  - rtl_433_statsd_pipe.py: Send data to statsd
+  - rtl_433_json_to_rtlwmbus.py: convert rtl_433 wmbus json output to rtlwmbus output
+
 # Strategies for Processing, Transmitting and Storing
 
 (This does not belong here, but is useful to those contemplating the