Initial Commit

docs/pinout.md

@@ -0,0 +1,56 @@
+## Pinouts
+
+![Emporia Vue Utility device](device_800.jpg)
+
+### P1
+
+JTAG header for the ESP32 module.  The pinout is the same as as the [ESP-Prog](https://docs.espressif.com/projects/espressif-esp-iot-solution/en/latest/hw-reference/ESP-Prog_guide.html)
+
+| Pin | ESP Pin | ESP Port | Description |
+| --- | ------- | -------- | ----------- |
+|  1  |         |          |      +3v3   |
+|  2  |    13   |  GPIO14  |   JTAG TMS  |
+|  3  |         |          |        GND  |
+|  4  |    16   |  GPIO13  |   JTAG TCK  |
+|  5  |         |          |        GND  |
+|  6  |    23   |  GPIO15  |   JTAG TDO  |
+|  7  |         |          |        GND  |
+|  8  |    14   |  GPIO12  |   JTAG TDI  |
+|  9  |         |          |        GND  |
+| 10  |     3   |          |         EN  |
+
+### P2
+
+Power supply 
+
+| Pin | Description |
+| --- | ----------- |
+|  1  |        +5v  |
+|  2  |       +3v3  |
+|  3  |        GND  |
+
+### P3
+
+ESP32 Serial programming interface.  Note that pin 6 is 5 volt, not 3.3 volt.
+
+| Pin | ESP Pin | ESP Port |
+| --- | ------- | -------- |
+|  1  |    25   |   GPIO0  |
+|  2  |     3   |      EN  |
+|  3  |         |     GND  |
+|  4  |    35   |      TX  |
+|  5  |    35   |      RX  |
+|  6  |         |     +5v  |
+
+
+### P4
+
+JTAG interface to the MGM111 module
+
+### P5
+
+| Pin | ESP Pin | MGM111 Pin | Description |
+| --- | ------- | ---------- | ----------- |
+|  1  |  GPIO21 |            |    ESP RX   |
+|  2  |  GPIO22 |            |    ESP TX   |
+|  3  |         |            |       GND   |

docs/protocol.md

@@ -0,0 +1,55 @@
+# Protocol details
+
+Each message sent or received begins with a `$` (hex 24).  Messages end with a carrage return (`\r` / hex 0D).
+
+### Message types
+
+| Msg char | Hex value | Description |
+| -------- | --------- | ----------- |
+| r        |  0x72  | Get meter reading |
+| j        |  0x6a  | Join the meter |
+| m        |  0x6d  | Get mac address (of the MGM111)|
+| i        |  0x69  | Get install code |
+| f        |  0x66  | Get firmware version |
+
+## Sending messages
+
+Messages from the ESP to the MGM111 have just the previously mentioned `$` starting delimiter, then a message type character and the 
+ending `\r` delimiter.  Each message is therefore exactly 3 bytes long.  For example, to get the a mac address, send the hex bytes
+`24 6D 0D` (`$m\r`)
+
+## Receiving responses
+
+Response format bytes:
+
+|  0 |  1 |  2 |  3 | ... | x |
+| -- | -- | -- | -- | --- | - |
+| `$` | 0x01 | *\<msg type\>* | *\<payload length\>* | *\<payload\>...* | `\r` |
+
+Byte 1, 0x01 indicates that this is a response
+Byte 2 is the same messages type that was used to trigger this response
+Byte 3 is the length of the payload that follows
+Bytes 4+ are the payload of the response
+The final byte is the terminator
+
+Ex:  
+`24 01 6D 08 11 22 33 44 55 66 77 88 0D`
+
+#### Mac address response payload
+The mac address reponse bytes are in reverse order, if the device responds with `11 22 33 44 55 66 77 88` then the mac address is
+`88:77:66:55:44:33:22:11`
+
+#### Install code response payload
+The install code bytes are also swapped, see mac address response above
+
+#### Meter reading response payload
+
+| Bytes | Meaning |
+| ----- | ------- |
+| 0 - 3 | Unknown, usually zeros |
+| 4 - 8 | Watt hours consumed.  Sometimes an invalid number greater than `0x0040 0000` is returned, which is not well understood |
+| 9 - 45 | Unknown, seems to always be zeros |
+| 46 - 50 | Unknown, seems to typically be `0x0000 0001` |
+| 51 - 55 | Potentially a Watt-Hour to kWh divisor, typically `0x0000 0x03E8` (1000) |
+| 56 - 60 | Current watts being consumed |
+| 61+ | Unknown |