fix: add help pages

Author: Stefano Bertelli

README.md

@@ -2,7 +2,7 @@
 
 [![Discord](https://img.shields.io/discord/1386014070632878100?style=social)](https://discord.gg/EDtgj7Yayr) [![Shop at Provvedo](https://img.shields.io/badge/Shop-Provvedo-blue?logo=shopify&style=flat-square)](https://www.provvedo.com/shop)
 
-A **Kivy-based Digital Read-Out (DRO) and single-axis controller UI** for rotary tables and similar devices, designed to run on Raspberry Pi or desktop environments (Windows, macOS, Linux). Interfaces via RS-485 with a dedicated STM32-based control board.
+A **Kivy-based Digital Read-Out (DRO) and single-axis controller UI** for rotary tables and similar devices, designed to run on Raspberry Pi or desktop environments (Windows, macOS, Linux). Interfaces via RS-485/Modbus RTU with a dedicated STM32-based control board.
 
 🛒 **Purchase all boards from our shop:** [Provvedo Shop](https://www.provvedo.com/shop)
 
@@ -11,25 +11,30 @@ A **Kivy-based Digital Read-Out (DRO) and single-axis controller UI** for rotary
 ## 🚀 Features
 
 * Responsive touch-capable UI built with **Kivy**
-* Communicates over **RS-485** with an STM32 controller for stepper/encoder control ([github.com][1])
-* Works on Raspberry Pi 3/4, Windows, macOS, and Linux
-* Runs headless on Pi using the custom **OSPI** OS with pre-installed RCP ([github.com][1])
+* Communicates over **RS-485 Modbus RTU** with an STM32 controller ([rotary-controller-f4](https://github.com/bartei/rotary-controller-f4))
+* **Configurable axes** — add/remove axes, assign hardware scale inputs, apply transforms (identity, scaling, weighted sum, angle cos/sin)
+* **Electronic Lead Screw (ELS)** mode for synchronized threading and power feed on manual lathes
+* **Sync mode** with configurable gear ratios for spindle-synchronized movement
+* **Circle pattern calculator** for bolt hole patterns
+* Customizable display: fonts, colors, digit formats (metric/imperial/angle)
+* **Contextual help** — info button on every setting field with documentation and examples
+* Works on Raspberry Pi 3/4/5, Windows, macOS, and Linux
+* Runs headless on Pi using the custom **OSPI** OS with pre-installed RCP ([ospi](https://github.com/bartei/ospi))
 
 ---
 
 ## 🎯 Requirements
 
 * **Hardware**
 
-  * Rotary controller board (STM32 firmware from `bartei/rotary-controller-f4`)
+  * Rotary controller board (STM32 firmware from [rotary-controller-f4](https://github.com/bartei/rotary-controller-f4))
   * RS-485 interface (e.g. via Power Hat)
-  * Raspberry Pi 3/4 for Pi deployments
+  * Raspberry Pi 3/4/5 for Pi deployments
 
 * **Software**
 
-  * Python 3.8+
-  * `uv` virtual environment manager
-  * `kivy`, `pyserial`, and other dependencies from `pyproject.toml`
+  * Python 3.10+
+  * [`uv`](https://docs.astral.sh/uv/) package manager
 
 ---
 
@@ -50,19 +55,24 @@ Install `uv` (Linux/macOS):
 curl -LsSf https://astral.sh/uv/install.sh | sh
 ```
 
-For Windows, follow instructions on the \[Astral uv docs].
+For Windows, see the [uv installation docs](https://docs.astral.sh/uv/getting-started/installation/).
 
-### 3. Create & Sync Virtual Environment
+### 3. Install Dependencies
 
 ```bash
-uv venv       # creates .venv/
-uv sync       # installs required dependencies
+uv sync
 ```
 
 ### 4. Run the App
 
 ```bash
-uv run python ./rcp/main.py
+uv run python -m rcp.main
+```
+
+### 5. Run Tests
+
+```bash
+uv run pytest
 ```
 
 ---
@@ -71,9 +81,9 @@ uv run python ./rcp/main.py
 
 ### Windows/macOS/Linux
 
-* Use Python >=3.8
-* Virtual environment recommended via `uv`
-* Ensure `pyserial` can access your RS-485 adapter (permissions on Linux/macOS)
+* Python >= 3.10
+* Virtual environment managed automatically by `uv`
+* Ensure your RS-485 adapter is accessible (check serial port permissions on Linux/macOS)
 
 ### Raspberry Pi & OSPI
 
@@ -98,18 +108,47 @@ uv run python ./rcp/main.py
 
 ---
 
+## 📂 Project Structure
+
+```
+rcp/
+├── main.py                    # Entry point (asyncio + Kivy event loop)
+├── app.py                     # MainApp class
+├── feeds.py                   # Feed/thread pitch configurations
+├── help/                      # Contextual help documents (markdown)
+├── components/                # UI layer
+│   ├── home/                  # Home screen (coordbar, servobar, elsbar, statusbar)
+│   ├── screens/               # Full-screen views (setup, scale, servo, formats, etc.)
+│   ├── widgets/               # Reusable form widgets with help button support
+│   ├── popups/                # Modal dialogs (keypad, help, feeds table, etc.)
+│   ├── toolbars/              # Toolbar buttons
+│   └── plot/                  # Plot/visualization
+├── dispatchers/               # Event dispatchers and state management
+│   ├── saving_dispatcher.py   # Auto-persisting properties to YAML
+│   ├── formats.py             # Display format settings
+│   ├── circle_pattern.py      # Circle pattern calculator
+│   └── board.py               # Board/device event dispatcher
+└── utils/                     # Hardware communication layer
+    ├── communication.py       # ConnectionManager (Modbus RTU)
+    ├── base_device.py         # C typedef parser and register I/O
+    └── devices.py             # Device type definitions
+```
+
+---
+
 ## 🛠️ Troubleshooting
 
 * **Serial issues**: Verify RS-485 wiring, correct serial port, and permissions
-* **Service failures (Pi)**: Check `journalctl` logs and Kivy log files, check the /var/log folder for OSPI release
+* **Service failures (Pi)**: Check `journalctl` logs and Kivy log files under `/var/log/`
+* **Display issues**: Adjust font size and display format in the Formats setup screen
 
 ---
 
 ## 📚 References & Related Projects
 
-* **Firmware & hardware:** \[rotary-controller-f4] ([github.com][3])
-* **PCB design & BOM:** \[rotary-controller-pcb] ([github.com][4])
-* **OSPI OS with pre-installed RCP:** \[ospi] ([github.com][2])
+* **Firmware & hardware:** [rotary-controller-f4](https://github.com/bartei/rotary-controller-f4)
+* **PCB design & BOM:** [rotary-controller-pcb](https://github.com/bartei/rotary-controller-pcb)
+* **OSPI OS with pre-installed RCP:** [ospi](https://github.com/bartei/ospi)
 
 ---
 
@@ -131,21 +170,10 @@ Contributions are welcome! Please:
 
 ## 🏆 Support
 
-Join our Discord community for support, collaboration, and updates.
+Join our [Discord community](https://discord.gg/EDtgj7Yayr) for support, collaboration, and updates.
 
 ---
 
 ## 📄 License
 
-Licensed under MIT. See `LICENSE` for full terms.
-
----
-
-*README last updated: June 23, 2025*
-
----
-
-[1]: https://github.com/bartei/rotary-controller-python"
-[2]: https://github.com/bartei/ospi"
-[3]: https://github.com/bartei/rotary-controller-f4"
-[4]: https://github.com/bartei/rotary-controller-pcb"
+Licensed under MIT. See `LICENSE` for full terms.

rcp/components/popups/help_popup.kv

@@ -0,0 +1,28 @@
+<HelpPopup>:
+  size_hint: 0.85, 0.85
+  auto_dismiss: True
+
+  BoxLayout:
+    orientation: "vertical"
+    padding: 10
+    spacing: 8
+
+    ScrollView:
+      do_scroll_x: False
+      do_scroll_y: True
+
+      Label:
+        text: root.help_text
+        size_hint_y: None
+        height: self.texture_size[1] + 20
+        text_size: self.width, None
+        font_size: 16
+        halign: "left"
+        valign: "top"
+        markup: False
+
+    Button:
+      size_hint_y: None
+      height: 50
+      text: "Close"
+      on_release: root.dismiss()

rcp/components/popups/help_popup.py

@@ -0,0 +1,22 @@
+from kivy.logger import Logger
+from kivy.properties import StringProperty
+from kivy.uix.modalview import ModalView
+
+from rcp.utils.kv_loader import load_kv
+
+log = Logger.getChild(__name__)
+load_kv(__file__)
+
+
+class HelpPopup(ModalView):
+    help_text = StringProperty("")
+
+    @staticmethod
+    def show_help(help_file: str):
+        if not help_file:
+            return
+        from rcp.app import MainApp
+        app = MainApp.get_running_app()
+        text = app.load_help(help_file)
+        popup = HelpPopup(help_text=text)
+        popup.open()

rcp/components/screens/axis_screen.kv

@@ -24,10 +24,12 @@
         StringItem:
           name: "Axis Name"
           value: root.axis.axis_name if root.axis else "?"
+          help_file: "axis_name.md"
           on_value: root.axis.axis_name = self.value
         BooleanItem:
           name: "Spindle Mode"
           value: root.axis.spindleMode if root.axis else False
+          help_file: "spindle_mode.md"
           on_value: root.axis.spindleMode = self.value
 
         TitleItem:
@@ -36,11 +38,13 @@
           name: "Sync Ratio Numerator"
           value: root.axis.syncRatioNum if root.axis else 360
           integer: True
+          help_file: "sync_ratio.md"
           on_value: root.axis.syncRatioNum = int(self.value)
         NumberItem:
           name: "Sync Ratio Denominator"
           value: root.axis.syncRatioDen if root.axis else 100
           integer: True
+          help_file: "sync_ratio.md"
           on_value: root.axis.syncRatioDen = int(self.value)
 
         TitleItem:
@@ -49,12 +53,14 @@
           name: "Transform Type"
           value: root.transform_type_label
           options: ["Identity", "Scaling", "Weighted Sum", "Angle Cos", "Angle Sin"]
+          help_file: "transform_type.md"
           on_value: root.transform_type_label = self.value
 
         DropDownItem:
           name: "Scale Input"
           options: root.input_0_options
           value: root.input_0
+          help_file: "scale_input.md"
           on_value: root.input_0 = self.value
 
         # Scaling params
@@ -63,12 +69,14 @@
           name: "Weight Numerator"
           value: root.weight_num
           integer: True
+          help_file: "weights.md"
           on_value: root.weight_num = int(self.value)
         NumberItem:
           disabled: root.transform_type_label not in ["Scaling", "Weighted Sum"]
           name: "Weight Denominator"
           value: root.weight_den
           integer: True
+          help_file: "weights.md"
           on_value: root.weight_den = int(self.value)
 
         # Weighted Sum second input
@@ -77,25 +85,29 @@
           name: "Second Scale Input"
           options: root.input_1_options
           value: root.input_1
+          help_file: "scale_input.md"
           on_value: root.input_1 = self.value
         NumberItem:
           disabled: root.transform_type_label != "Weighted Sum"
           name: "Second Weight Numerator"
           value: root.weight_1_num
           integer: True
+          help_file: "weights.md"
           on_value: root.weight_1_num = int(self.value)
         NumberItem:
           disabled: root.transform_type_label != "Weighted Sum"
           name: "Second Weight Denominator"
           value: root.weight_1_den
           integer: True
+          help_file: "weights.md"
           on_value: root.weight_1_den = int(self.value)
 
         # Angle params
         NumberItem:
           disabled: root.transform_type_label not in ["Angle Cos", "Angle Sin"]
           name: "Angle (degrees)"
           value: root.angle_degrees
+          help_file: "angle_degrees.md"
           on_value: root.angle_degrees = self.value
 
     BoxLayout:

rcp/components/screens/els_setup_screen.kv

@@ -23,12 +23,15 @@
         DropDownItem:
           id: spindle_dropdown
           name: "Spindle Axis"
+          help_file: "els_axis_roles.md"
           on_value: root.on_spindle_selected(self, self.value)
         DropDownItem:
           id: z_dropdown
           name: "Saddle Axis (Z)"
+          help_file: "els_axis_roles.md"
           on_value: root.on_z_selected(self, self.value)
         DropDownItem:
           id: x_dropdown
           name: "Cross Slide Axis (X)"
+          help_file: "els_axis_roles.md"
           on_value: root.on_x_selected(self, self.value)