examples: Improve README by describing scripts (#2976)

Expand description of the directory, making it clearer that some
programs have production use.

Declare that python scripts are python3.  It's clear that nobody is
trying to use them with python 2.7, and if they did, we would tell
them not to.

List the scripts with a one-line description, sorting them into
production (none yet), generally usable, and true examples.  Leave
some uncategorized.

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