add errata and next steps

README.md

@@ -52,6 +52,234 @@ auf RS485. Die Steuerung läuft im Keller auf einem Linux, z.B. auf vogon.
       oder Raspi oder so, die ebenfalls kaputtgehen könnten.
 
 
+Errata for V1.0
+---------------
+
+### No fix needed
+
+1. Varistor on 24V is more than fast enough but we could add a TVS in parallel for longer life span.
+   - Fix if we ever have a dead varistor (or one that has significant leakage current).
+2. WS2811 should have 33R series resistance.
+   - We do have 27R, which should be close enough.
+3. USB host mode might be useful.
+   - It was left out because we didn't have enough current available at 5V when that
+     was decided. If we keep that in the next revision, we could consider it again.
+   - It might be useful for adding additional hardware but things like BLE and Zigbee
+     are better added via SPI/I2C/UART, which should be easier (unless we have enough uses
+     for low-speed USB to make a generic tunnel, e.g. as an USB-IP device on the other end).
+   - What would be needed?
+     - Pull CC lines high instead of low at the request of the MCU (needs another pin)
+       but always pull them low by default (for the bootloader).
+     - Supply VBUS at the request of the MCU (needs a pin but maybe the same one).
+     - Current limit for VBUS, e.g. with PTC fuse.
+   - Alternative: External adapter to USB-A that also provides power supply (e.g. using
+     our 5V output on J1 pin 14, which is already fused for 500 mA).
+   - Alternative: Attach device inside the case and use a different protocol (I2C/SPI/UART)
+     or attach it to an existing Linux computer (if it doesn't have to run while the room
+     is powered down).
+
+### Change for new revision (if we ever have one)
+
+1. WS2811 should have 100R series resistance on VDD.
+   - Datasheet sounds like this is optional for 5V so let's hope for the best.
+   - Hotfix is unlikely for current PCB so backup plan is to remove the WS2811.
+2. WS2812C-2020-V1 datasheet doesn't have the 33R series resistance but we maybe want to add it anyway.
+3. Add DCDC to main PCB if we have the space.
+   - We could use RT7272, which has an adjustable current limit. That way, we can use a
+     smaller inductor but we will have less current available for external circuits (i.e.
+     adjust the fuses, as well).
+
+### Hotfix would be useful
+
+1. RS485 common mode range goes from -7V to +12V but the TVS clamps it to -0.7V to 6V.
+  - If we use the full 12 A on 1 mm² wires (2x 0.5 mm²), we could have a ground offset of
+    4V. RS485 could handle that but not with the TVS clamping it to a smaller range.
+  - The TVS is shared by WS2811. WS2811 seems to have ESD diodes (educated guess based on
+    abs max values) so the series resistors might even die before the diodes if it ever
+    comes to that so the WS2811 should be fine (enough) without the TVS. Furthermore, the
+    WS2811 is an optional feature while RS485 is essential.
+  - The RS485 transceiver has plenty of ESD protection already so it shouldn't need the
+    TVS anyway. It was added as an afterthought because "it couldn't hurt" - oh, well,
+    turns out that it can!
+  - (We don't actually know that this will be an issues, i.e. we haven't tested it, but
+     we would rather be safe than sorry and it is easier to fix it from the start.
+     Actually, we don't expect any issues at all with the main use case, which will only
+     need at most 2 A instead of 12 A, but we don't want it to fail later after someone
+     adds lots of LEDs.)
+  - **Hotfix**: Remove U11 (and maybe replace it by a suitable SOT-23 TVS just for WS2811)
+  - Proper fix for new revisions: Keep U11 for WS2811 but disconnect it from the RS485
+    signals. There are dedicated TVS for RS485 that we could consider.
+  - Side note: The WS2811 signal is from board to board so it should see a much lower
+    ground offset. We would expect something like 0.5V, which is still in the spec. If we
+    have an offset of 1V, we will send 19 mA through the ESD diodes (limited by the series
+    resistor), which isn't great but should be harmless.
+
+### Planned changes before deploying the boards
+
+(Those aren't really errata, of course, but we will do that at the same time as the hotfixes so this is a good place to put it.)
+
+- Test, test, test!
+- Adjust R64 to have suitable volume for the beeper (when inside the case).
+- Add BZ1 and J1.
+- Add DCDC board.
+- Bend F3 upwards (and a bit to the left) to have more space for wires at J1.
+- Add "Anschlussplan".
+
+
+Next Steps
+----------
+
+- [x] order PCBs (JLC PCBA)
+- [x] order other parts (LCSC)
+- [ ] test basic function (bootloader, flash, blinky, USB)
+- [ ] test essential functions
+  - LEDs
+  - RS485
+  - on/off control for heater
+  - some debug info on USB, e.g. debug console on emulated USB serial
+  - CJ431 (just measure the voltage)
+  - DCDC stand-alone test
+  - supply main board from 24V, shouldn't back-feed to VBUS
+  - measure VCC with ADC
+  - DIGIN1/2/3/4 (short to GND or not - like they will be with Reed switches)
+  - maybe DS18B20
+- [ ] basic communication, i.e. write modbus code for RP2040 and Linux
+- [ ] test other functions (part of it can be in parallel with alpha/beta/gamma tests)
+  - measure heater current, with and without EN_MEASURE_CURRENT
+    - implement short-circuit detection for heaters
+  - WS2811: connect DIGOUT to WS2811-in and connect a few boards
+  - I2C: temperature sensor
+  - beeper: simple beeps; very optional: MIDI and PCM
+  - DIGOUT1/2: DS18B20
+  - ANALOG_IN1
+  - 5V ext, including to test the fuse
+  - display: buttons
+  - display, I2C: temperature sensor
+  - display, OLED
+  - display, touch
+  - display, WS2812
+  - MicroPython and/or LVGL for the UI
+- [ ] alpha test:
+  - 1-2 boards (e.g. in .cook and .elab)
+  - actuator connected to board but not controlling the actual valve, yet
+  - preferrably with one display board for first user feedback
+  - What do we test here?
+    - Basic function.
+    - Unexpected issues.
+    - First user feedback.
+- [ ] beta test:
+  - mount boards in the final places, with final wiring
+  - including all display boards and all sensors
+  - If we want dedicated boards for temperature sensors (e.g. .make over the working area),
+    we should also add them now.
+  - Connect as many actuators as we have (but don't buy any additional ones, yet). We can
+    connect them to the valves if we want but the power use of the normally-open actuator
+    would be a waste in summer and we might need them for additional tests (which is easier
+    when they aren't already mounted).
+  - Log everything to InfluxDB+Grafana.
+  - What do we test here?
+    - Monitor for communication errors and other reliability issues.
+    - Logging and graphs.
+    - Optional: Dry-run for integrations, e.g. edi and/or home assistant.
+- [ ] gamma test:
+  - Normal operation for one room, e.g. .hack or .elab. If we do this in .hack, we might
+    want to start without the third radiator because it is not so easy to reach it in case
+    of problems.
+  - What do we test here?
+    - Basic temperature control.
+    - Unexpected issues.
+- [ ] rollout:
+  - buy and connect all the actuators
+- [ ] optional parts: hardware (optional, i.e. not necessarily done by us)
+  - Reed switches
+  - more DS18B20, e.g. two for each radiator
+  - control fans in .hack - can we simply do this with one of the heater outputs (with the
+    high side connected to 12V, of course)?
+- [ ] basic software features
+  - RS485 USB adapter passed through to Python software in container on vogon.
+  - simple way of adding new devices, e.g. press ADR button on one device and set its
+    Modbus address via broadcast ("if your button is pressed, use this address from now on
+    and store that in persistent storage"). This can be CLI or web interface.
+    - In general, I would like to avoid using persistent configuration on the boards.
+      The central controller needs to know some parts anyway (i.e. they might become
+      inconsistent) and users can more easily change this on a Linux (including for boards
+      that are currently offline).
+  - configuration, e.g. a YAML file with info for each device: Modbus ID, room, how many
+    heaters are connected, with display board
+  - simple user interface with OLED and buttons:
+    - display actual temperature
+    - set desired temperature
+    - set duration
+    - automatically reset to standby temperature after some hours
+  - basic monitoring: preferrably Grafana, but CSV+syslog would do the job
+  - basic temperature control: simple two-point regulator will suffice
+- [ ] fancy software features, maybe for V1.0 (all semi-optional)
+  - simple web UI for configuration and troubleshooting
+  - semi-automatic adding of new devices, e.g. scan by UID and identify by button or LED
+  - auto-baud or switch-baud command, i.e. start at a safe speed by default but have a way
+    to upgrade it (but without race conditions and other pitfalls, please!)
+  - auto-detect order of boards by WS2811 signal (if first board has DIGOUT connected to
+    WS2811-in)
+  - auto-detect whether heater valve actuators are connected (via EN_MEASURE_CURRENT)
+  - auto-detect whether display is connected
+  - touch control in addition to buttons
+    - The buttons will always be available as a fallback unless the touch turns out to be
+      exceptionally reliable.
+  - function of DIGOUT configurable by Modbus and maybe some auto-detection (scan for I2C
+    and DS18B20 devices on start or when requested)
+  - diagnostics:
+    - detect when boards are reset (by changing some register from its reset value to
+      "I have seen you" and boards respond to a certain broadcast after reset so we can
+      easily find them during normal operation even if we have never seen them before)
+    - error counters for each device and maybe even full Modbus diagnostics, log to Grafana
+      for each device
+    - send the correct error replies (Modbus spec seems quite reasonable for this, even if
+      we won't see many of the errors in practice, e.g. register not supported);
+      and log errors
+  - better user feedback
+    - use the beeper when it makes sense (and only then)
+    - notify when the timer is expired
+    - acknowledge user input in a responsive way (local feedback, quick!, intuitive)
+      but also be honest (i.e. indicate when the central controller hasn't acknowledged
+      a change, yet)
+  - power saving:
+    - dim or turn off display and LEDs when not in use (until button is pressed or touch
+      detects hand is near)
+    - let the MCU sleep
+  - fancy heat control:
+    - measure resistance to estimate current position
+    - closed-loop control for target resistance instead of simple open/closed control
+    - optional: correct overshoot. The heat seems to need some time to distribute, i.e.
+      resistance and position will continue change after power is turned off.
+    - Measure resistance to position curve.
+      - This could be good for a blog post.
+    - Measure resistance to heat of radiator curve (probably a long-term test, can be done
+      later based on Grafana data if we have the sensors).
+    - Make a heating model for each room, e.g. measure step response for a few radiators
+      and then see where this takes us.
+    - We will probably stop here and just use a PI/PID controller but we may want to
+      compensate for dead time, e.g. estimate expected future change of heat based on
+      valve position history (or radiator temperature if we have that) and add this to the
+      currently measured temperature.
+- [ ] future software features in Python (all optional, i.e. not necessarily done by us)
+  - This can all be done in Python on Linux so we can defer this until someone needs it and
+    then they can implement what they actually need and have a real-world use case to
+    design the API for (which is usually a good thing unless you are very lazy and only
+    design it for your case and your case alone).
+  - APIs could be HTTP or MQTT, for example.
+  - API: set desired temperature for each room (maybe with several settings for each room,
+    each with a name, time range and priority)
+  - API: let devices on the network communicate with Modbus devices
+  - API: show info on display or LEDs
+    - fxk8y's UDP protocol for LEDs might be a sensible choice.
+  - API: add items to the menu and receive a callback when they are activated
+- [ ] future software features, (partially) in firmware
+      (all optional, i.e. not necessarily done by us)
+  - ringclock
+  - MIDI over Modbus
+  - PCM over Modbus (with Pulseaudio sink on vogon)
+
+
 Main PCB
 --------
 
@@ -237,6 +465,8 @@ Zusätzliche Nutzung
   - Siehe oben für mehr Details zu den verfügbaren Pins und siehe Schaltplan für kreative Nutzung abseits des offensichtlichen,
     z.B. die Digitaleingänge als Ausgang nutzen.
   - 3 IOs komplett ungenutzt (aber Beschaltung beachten), z.B. WS2812, DS18B20 oder I2C
+    - 0fr0 suggested two DS18B20 per radiator (one at each end) so we can double-check the
+      function of actuator, valve and central heating.
   - 4x Reed-Eingang, wenn nicht für Fenster genutzt.
   - Der Wannenstecker kann im Prinzip genutzt werden, wenn kein Display dran hängt, aber nicht nach draußen legen, weil da ist
     keine Schutzbeschaltung dran. Wenn du das vorhast, nimm bitte ein dediziertes Board. Wenn ein Display dran ist, kann man nur