Claude/document repository overview #1609

envariant · 2025-11-12T00:53:44Z

No description provided.

Created a detailed REPOSITORY_OVERVIEW.md document that includes: - Project introduction and purpose - Complete repository structure breakdown - Architecture overview with component descriptions - Detailed documentation of all core components (Configuration, Machine, Motors, Spindles, Kinematics, etc.) - Build system documentation and PlatformIO configuration - YAML configuration system explanation - Development guidelines and coding standards - Installation and usage instructions - Contributing guidelines - Resource links and quick reference guide - Conceptual architecture diagram This document serves as a comprehensive guide for developers and users to understand the FluidNC firmware structure, usage, and development.

Extended REPOSITORY_OVERVIEW.md with detailed functional documentation: - Machine States: Complete state machine description (Idle, Alarm, Cycle, Hold, etc.) - Realtime Commands: Feed hold (!), cycle start (~), reset (Ctrl-X), overrides - Control Input Pins: E-stop, safety door, feed hold, cycle start, reset, macros - Status Output Pins: State-based outputs for tower lights (idle, run, hold, alarm, door) - Pause/Resume: Detailed feed hold and cycle start behavior - Emergency Stop Levels: Soft (feed hold), hard (e-stop pin), critical (reset) - Alarm States: All alarm types with causes and recovery procedures - Alarm Recovery: $X unlock command and after_unlock macro - Safety Door/Parking: Automatic parking sequence configuration and operation - Soft vs Hard Limits: Software vs physical limit handling - Event-Triggered Macros: startup, after_homing, after_reset, after_unlock - User I/O: Digital/analog inputs and outputs with G-code control - Practical Examples: E-stop setup, door control, dust collection automation This documentation provides operators and integrators with complete information on how FluidNC handles operational states, safety features, and how to configure pin-based control and automation.

Added detailed "Serial Communication and RS-485" section covering: UART Configuration: - ESP32 UART hardware (3 UARTs: UART0 fixed, UART1-2 configurable) - Configuration parameters (TXD, RXD, RTS, CTS pins) - Baud rates (2400-10M), mode string format (8N1, 8E1, etc.) RS-485 Support: - Differential signaling, long distance (1200m), multi-drop capability - Hardware requirements (MAX485, MAX3485, SN65HVD75 transceivers) - Wiring diagrams for ESP32 to RS-485 connection - Half-duplex mode with automatic RTS-controlled TX/RX switching - Termination resistor requirements Modbus RTU Protocol: - Protocol structure (Device ID, Function Code, Data, CRC16) - Common function codes (0x03 Read, 0x06 Write Single, 0x10 Write Multiple) - CRC-16 calculation details - Example Modbus command/response breakdown VFD Spindle Control: - 8 pre-configured VFD protocols (Huanyang, H2A, H100, YL620, Siemens V20, Danfoss VLT2800, NowForever, Generic) - Complete configuration examples with inline/external UART - VFD setup requirements and parameter configuration - Generic protocol for custom VFDs with Modbus command templates - Polling mechanism, command queuing, error handling Trinamic Stepper UART: - TMC2208/TMC2209 single-wire UART communication - Addressable drivers (0-3 per UART) - Live configuration (current, microstepping, modes) - Multi-driver configuration examples Dynamixel Servo Communication: - Robotis Protocol 2.0 over RS-485 - Closed-loop control with encoder feedback - Addressable (up to 253 servos) - Configuration for rotary axes UART Channels: - User application communication - Secondary GCode input - Debug output configuration Practical Examples: - VFD spindle with Huanyang (complete wiring + config) - Mixed TMC steppers and VFD on separate UARTs - Dynamixel servo axis configuration Troubleshooting: - VFD, TMC, and RS-485 common issues - Debug command reference - Solutions for wiring and configuration problems Capabilities Summary: - Feature comparison table - Maximum UART configuration overview This documentation provides complete information for integrators using RS-485 VFDs, Modbus RTU devices, TMC steppers, and Dynamixel servos with FluidNC.

MitchBradley

Overall this is an impressive summary but it does have some blatant errors, some of which I found in a quick reading. There are probably others.

What is the plan for keeping it up to date? Stale documentation can be troublesome.

MitchBradley · 2025-11-12T03:15:41Z

REPOSITORY_OVERVIEW.md

+
+**VFD Protocols** (`FluidNC/src/Spindles/VFD/`):
+- Huanyang protocol variants
+- Modbus RTU communication


There are many other VFD protocols and none of them are variants of the Huanyang protocol. The most important one, the generic "ModbusVFD", is not mentioned. There is a later section that is much better. This one is so sparse as to be misleading

MitchBradley · 2025-11-12T03:16:38Z

REPOSITORY_OVERVIEW.md

+- ESP32 framework libraries (ArduinoOTA, DNSServer, ESPmDNS, WebServer)
+
+### Building the Project
+


Building via bash is the least important case. Nearly everyone uses VsCode.

MitchBradley · 2025-11-12T03:18:59Z

REPOSITORY_OVERVIEW.md

+### Version Management
+
+The build system uses `git-version.py` to automatically inject git version information into the firmware.
+


The most important aspects of version management are embodied by "build-release.py" and the manual.yml github actions workflow that creates and publishes release builds.

MitchBradley · 2025-11-12T03:19:32Z

REPOSITORY_OVERVIEW.md

+  enable_pin: gpio.4
+
+# Additional components...
+```


This section is way too sparse.

MitchBradley · 2025-11-12T03:24:19Z

REPOSITORY_OVERVIEW.md

+**Enabling Soft Limits:**
+```bash
+$Limits/Soft=On       # Enable soft limit checking
+```


This is just wrong. There is no $limits/soft=on command. You have to enable them in the config file.

MitchBradley · 2025-11-12T03:31:42Z

REPOSITORY_OVERVIEW.md

+
+#### Hardware Requirements
+
+**RS-485 Transceiver IC Examples:**


This section is not particularly helpful

MitchBradley · 2025-11-12T03:34:32Z

REPOSITORY_OVERVIEW.md

+**Use Cases:**
+- Secondary GCode input
+- External controller communication
+- Sensor data logging


"Sensor data logging" is not a use case that I have seen for FluidNC UART channels.

MitchBradley · 2025-11-12T03:35:15Z

REPOSITORY_OVERVIEW.md

+
+### Practical Serial Communication Examples
+
+#### Example 1: VFD Spindle with Huanyang


This section is pretty much redundant with earlier VFD stuff

MitchBradley · 2025-11-12T03:37:22Z

REPOSITORY_OVERVIEW.md

+**Maximum Configuration:**
+- UART0: USB console (fixed)
+- UART1: TMC steppers or VFD
+- UART2: VFD or Dynamixel or second peripheral


"Second peripheral" is vague/meaningless. The most important other use case is as an I/O Expander and or Pendant channel.

MitchBradley · 2025-11-12T03:39:34Z

REPOSITORY_OVERVIEW.md

+
+### Configuration Commands
+
+- `$Config/Filename=name.yaml` - Set active config


This is way too sparse. It should have a link to the complete information on the wiki

michmela44 · 2025-11-14T00:21:50Z

Overall this is an impressive summary but it does have some blatant errors, some of which I found in a quick reading. There are probably others.

What is the plan for keeping it up to date? Stale documentation can be troublesome.

While it is also out of date, this is also a very impressive AI generated summary.

https://deepwiki.com/bdring/FluidNC/1-fluidnc-overview

I clicked the button just now to get it to refresh since it hasn't updated since April.

It does say you can add a badge or something to the repo and it will keep it auto up-to-date

MitchBradley · 2025-11-14T00:45:31Z

What is the advantage of checking it in vs regenerating it on the fly as needed? If it is checked in we are implicitly blessing it.

michmela44 · 2025-11-14T00:47:26Z

I'm not sure. I just saw it was there. I think if it's in the readme it automatically updates weekly. I don't know if there is a limit if done manually.

claude added 3 commits November 6, 2025 02:08

envariant closed this Nov 12, 2025

envariant reopened this Nov 12, 2025

MitchBradley reviewed Nov 12, 2025

View reviewed changes

		- ESP32 framework libraries (ArduinoOTA, DNSServer, ESPmDNS, WebServer)

		### Building the Project

		### Version Management

		The build system uses `git-version.py` to automatically inject git version information into the firmware.


		#### Hardware Requirements

		RS-485 Transceiver IC Examples:


		### Practical Serial Communication Examples

		#### Example 1: VFD Spindle with Huanyang


		### Configuration Commands

		- `$Config/Filename=name.yaml` - Set active config

Uh oh!

Claude/document repository overview #1609

Are you sure you want to change the base?

Claude/document repository overview #1609

Uh oh!

Conversation

envariant commented Nov 12, 2025

Uh oh!

MitchBradley left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

michmela44 commented Nov 14, 2025

Uh oh!

MitchBradley commented Nov 14, 2025

Uh oh!

michmela44 commented Nov 14, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants