intermediate: update doc

Readme.md

@@ -14,20 +14,29 @@ Have a simple ready-to-go ESP32 binary that can be flashed onto a [M5 Atom CAN](
 
 But will also run on other ESP32 boards.
 
-Modes
------
-* NMEA2000 -> Wifi (NMEA0183)
-* NMEA2000 -> USB (NMEA0183)
-* NMEA0183 -> Wifi
-* NMEA0183 -> NMEA2000
-* Wifi (NMEA0183) -> NMEA2000
-* USB (NMEA0183) -> NMEA2000
-* ....
+What is included
+----------------------------------
+* a NMEA2000 to Wifi (NMEA0183) gateway
+* a NMEA2000 to USB (NMEA0183) gateway
+* a NMEA0183 Multiplexer 
+  * Wifi to Wifi
+  * Wifi to USB
+  * Wifi to RS485
+  * and reverse
+* a NMEA0183 RS485 to NMEA2000 gateway
+* a Wifi (NMEA0183) to NMEA2000 gateway
+* an USB (NMEA0183) to NMEA2000 gateway
+* a WEB UI to configure the gateway and to show the data that has been received
+* a USB Actisense to NMEA2000 gateway
+* a NMEA2000 to USB Actisense gateway
+
+For the details of the mapped PGNs and NMEA sentences refer to [Conversions](doc/Conversions.pdf).
+
+Hardware
+--------
+The software is prepared to run on different kinds of ESP32 based modules and accessoirs. For some of them prebuild binaries are available that only need to be flashed, others would require to add some definitions of the used PINs and features and to build the binary.
+For the list of hardware set ups refer to [Hardware](doc/Hardware.md).
 
-Environment
------------
-[PlatformIO](https://platformio.org/).
-Should be possible to use [M5Burner](https://docs.m5stack.com/en/download) to flash ready binaries.
 
 Pre Build Binaries
 ------------------
@@ -37,18 +46,32 @@ The flash command must be (example for m5stack-atom):
 ```
 esptool.py --port XXXX --chip esp32 write_flash 0x1000  m5stack-atom-all.bin
 ```
-For the meaning of the boar names have a look in [platformio.ini](platformio.ini) and look for the hardware definitions in [GwHardware.h](lib/hardware/GwHardware.h).
+For the meaning of the board names have a look at [Hardware](doc/Hardware.md). For details refer to the code in [platformio.ini](platformio.ini) and look for the hardware definitions in [GwHardware.h](lib/hardware/GwHardware.h).
 
 Starting
 ---------
 After flushing a wifi access point is created. Connect to it (name: ESP32NMEA2K, password: esp32nmea2k).
 Afterwards use a Bonjour Browser, the address ESP32NMEA2k.local or the ip address 192.168.15.1 to connect with your browser.
 You will get a small UI to watch the status and make settings.
-If you want to connect to another wifi network, just enter the credentials in the wifi client tab.
+If you want to connect to another wifi network, just enter the credentials in the wifi client tab and enable the wifi client.
+For all the potential inputs and outputs (NMEA2000, USB, TCP, RS485) you can set the configuration including NMEA0183 filtering.
 On the data page you will have a small dashboard for the currently received data.
 On the status page you can check the number of messages flowing in and out.
 
-more to come...
+Conversion from and to NMEA0183 XDR
+-----------------------------------
+The gateway can convert a lot of NMEA 2000 PGNs that have no direct NMEA0183 equivalent to NMEA0183 XDR records. For details refer to [XdrMappings](doc/XdrMappings.md)
+
+Development Environment
+-----------------------
+[PlatformIO](https://platformio.org/).
+
+
+Extending the Software
+----------------------
+To give room for adding own software and still being able to keep in sync with this master part there is a concept of user tasks that will allow you to add your own hardware definitions and to add code that should be executed without the need to change parts of the existing software.
+For details refer to the [example description](lib/exampletask/Readme.md).
+
 
 
 

doc/XdrMappings.md

@@ -0,0 +1,60 @@
+Converting to and from NMEA0183 XDR records
+===========================================
+Basics
+------
+NMEA2000 has a much broader set of messages dealing with various sensor data then NMEA0183 has.
+In NMEA0183 there is (beside a small amount of predefined sentences) a more or less generic [XDR sentence](https://gpsd.gitlab.io/gpsd/NMEA.html#_xdr_transducer_measurement).
+As there is no out of the box complete mapping between NMEA2000 and NMEA0183 XDR possible you need to configure the mappings between NMEA2000 and XDR and vice versa.
+
+Mapping Parameters
+------------------
+Typically a NMEA2000 PGN that the gateway can map to an XDR record will belong to a certain category (like Temperature, Pressure, Engine,...), will potentially inlcude a source identifier (like SeaTemperature or OutsideTemperature), an instance id (0...255) and potentially a couple of fields (like EngineOilPressure, EngineCoolantTemp).
+You now need to select which combination of those values should be mapped to a particular XDR transducer name.
+
+![ExampleXDR](xdrconfig1.png)
+
+Simple Set Up
+-------------
+To make the configuration easy the gateway will record information about NMEA2000 PGNs it could in principle map to XDR records - but without a current configuration.
+Just click "Show Unmapped" to get a list of those entities.
+
+![ExampleList](xdrconfig2.png)
+
+By clicking the "+" button beside the entry you will get a prefilled mapping. You just need to add the transducer name and save the settings.
+
+Instance Id handling
+--------------------
+For the instance Id of a NMEA2000 message there are 3 options on how they can be used to convert to a transducer name:
+* single<br>
+  exactly only this instance id is mapped to the selected transducer name.
+  This should work for most receivers of the XDR records but requires a separate mapping for each of your instances.
+* auto<br>
+  In this mode the instance will be added to the transducer name in the form of Temperature#001 - 001 being the instance id. This is recommended in NMEA0183 4.x - but not necessarily received by all devices.
+* ignore<br>
+  All instances will map to the same transducer name.
+
+Backward Mapping
+----------------
+The configured mappings can work in both directions. So when an XDR record with a known transducer name, type and unit is received it is converted into a NMEA2000 PGN.
+You need to have the direction for the mapping set to "bidir" (the default).
+
+Export and Import
+-----------------
+The mappings can be exported and imported as a json file from the UI.
+
+Handled PGNs
+------------
+The following PGNS are handled:
+
+| Category | from NMEA2000 | to NMEA2000 |
+|----------|---------------|-------------|
+| Fluid    | 127505        | 127505      |
+| Battery  | 127508        | 127508      |
+| Temperature | 130310, 130311, 130312, 130316     | 130312      |
+| Pressure  | 130310, 130311, 130314 | 130314 |
+| Humidity | 130311, 130313 | 130313 |
+| Engine | 127489, 127488 | 127489, 127488 |
+
+Rate
+----
+To avoid resending the same XDR transducer to often you can set a minimum delay between sending it again (config/converter/min XDR interval, default 100ms).