amr-ros-k4/DOCUMENTATION.md

# Blockly ROS2 Robot Controller — Documentation

Visual programming interface for controlling a ROS2 Jazzy Kiwi Wheel AMR.
See [readme.md](readme.md) for project overview and status.

---

## Documentation Index

| Topic | File |
|---|---|
| System architecture & Blockly–ROS2 integration flow | [docs/architecture.md](docs/architecture.md) |
| Installation, directory structure & running | [docs/installation.md](docs/installation.md) |
| Troubleshooting & known issues | [docs/troubleshooting.md](docs/troubleshooting.md) |
| Guide: adding a new ROS2 package | [docs/ros2-package-guide.md](docs/ros2-package-guide.md) |
| `blockly_app` — file reference | [src/blockly_app/README.md](src/blockly_app/README.md) |
| `blockly_app` — creating custom blocks (full guide + reference) | [src/blockly_app/BLOCKS.md](src/blockly_app/BLOCKS.md) |
| `blockly_executor` — file reference, handlers & testing guide | [src/blockly_executor/README.md](src/blockly_executor/README.md) |
| `blockly_interfaces` — ROS2 action & message interfaces | [src/blockly_interfaces/README.md](src/blockly_interfaces/README.md) |
| `gpio_node` — Raspberry Pi GPIO node (C++, libgpiod) | [src/gpio_node/](src/gpio_node/) |

---

## Quick Start

### Desktop (linux-64)

```bash
pixi install                  # first time only
pixi run build-interfaces     # must build interfaces first
pixi run build                # build all packages
pixi run setup-ui             # download Blockly JS vendor files (first time, needs internet)

pixi run executor             # Terminal 1 — start Action Server
pixi run app                  # Terminal 2 — start desktop GUI
```

### Raspberry Pi (linux-aarch64)

```bash
pixi install                  # install ROS2 + deps via conda
pixi run build-gpio           # installs system deps (apt) + builds gpio_node

pixi run gpio-node            # start GPIO node
```

`build-gpio` automatically runs `setup-dep` which installs system libraries (`libgpiod-dev`, `liblttng-ust-dev`) via `apt`.

See [docs/installation.md](docs/installation.md) for full setup and prerequisites.
-												Add README files for blockly_app and blockly_executor; fix typo in digitalOut block

											
										
										
											2026-03-09 23:35:48 +07:00
+								# Blockly ROS2 Robot Controller — Documentation
-												initial with big achivement

											
										
										
											2026-03-07 11:13:06 +07:00
-												Add README files for blockly_app and blockly_executor; fix typo in digitalOut block

											
										
										
											2026-03-09 23:35:48 +07:00
+								Visual programming interface for controlling a ROS2 Jazzy Kiwi Wheel AMR.
 								See [readme.md](readme.md) for project overview and status.
-												initial with big achivement

											
										
										
											2026-03-07 11:13:06 +07:00
 								---
-												Add README files for blockly_app and blockly_executor; fix typo in digitalOut block

											
										
										
											2026-03-09 23:35:48 +07:00
+								## Documentation Index
-												initial with big achivement

											
										
										
											2026-03-07 11:13:06 +07:00
-												Add README files for blockly_app and blockly_executor; fix typo in digitalOut block

											
										
										
											2026-03-09 23:35:48 +07:00
+								| Topic | File |
-												initial with big achivement

											
										
										
											2026-03-07 11:13:06 +07:00
+								|---|---|
-												Add README files for blockly_app and blockly_executor; fix typo in digitalOut block

											
										
										
											2026-03-09 23:35:48 +07:00
+								| System architecture & Blockly–ROS2 integration flow | [docs/architecture.md](docs/architecture.md) |
 								| Installation, directory structure & running | [docs/installation.md](docs/installation.md) |
 								| Troubleshooting & known issues | [docs/troubleshooting.md](docs/troubleshooting.md) |
 								| Guide: adding a new ROS2 package | [docs/ros2-package-guide.md](docs/ros2-package-guide.md) |
 								| `blockly_app` — file reference | [src/blockly_app/README.md](src/blockly_app/README.md) |
 								| `blockly_app` — creating custom blocks (full guide + reference) | [src/blockly_app/BLOCKS.md](src/blockly_app/BLOCKS.md) |
 								| `blockly_executor` — file reference, handlers & testing guide | [src/blockly_executor/README.md](src/blockly_executor/README.md) |
-												Refactor Blockly Executor and GPIO Node Integration

- Updated blockly_app to replace LED blocks with digital input/output blocks.
- Added digitalIn.js and digitalOut.js blocks for reading and writing GPIO states.
- Removed led_on.js and led_off.js blocks as they are no longer needed.
- Modified manifest.js to include new digital blocks.
- Enhanced blockly_executor to handle digital input and output commands.
- Created a new Hardware context class to manage dummy and real hardware modes.
- Implemented GPIO node for Raspberry Pi to handle digital input/output via gpiod.
- Added GpioWrite and GpioRead message definitions for communication between executor and GPIO node.
- Updated tests to cover new digital input/output functionality and removed old LED tests.

											
										
										
											2026-03-10 21:22:09 +07:00
+								| `blockly_interfaces` — ROS2 action & message interfaces | [src/blockly_interfaces/README.md](src/blockly_interfaces/README.md) |
-												feat: port gpio_node to C++ using libgpiod; update package structure and dependencies for native Raspberry Pi support

											
										
										
											2026-03-12 10:27:47 +07:00
+								| `gpio_node` — Raspberry Pi GPIO node (C++, libgpiod) | [src/gpio_node/](src/gpio_node/) |
-												initial with big achivement

											
										
										
											2026-03-07 11:13:06 +07:00
 								---
-												Add README files for blockly_app and blockly_executor; fix typo in digitalOut block

											
										
										
											2026-03-09 23:35:48 +07:00
+								## Quick Start
-												initial with big achivement

											
										
										
											2026-03-07 11:13:06 +07:00
-												feat: update documentation for GPIO node setup and installation on Raspberry Pi; clarify C API usage

											
										
										
											2026-03-16 05:15:50 +07:00
+								### Desktop (linux-64)
-												initial with big achivement

											
										
										
											2026-03-07 11:13:06 +07:00
+								```bash
-												Add README files for blockly_app and blockly_executor; fix typo in digitalOut block

											
										
										
											2026-03-09 23:35:48 +07:00
+								pixi install                  # first time only
 								pixi run build-interfaces     # must build interfaces first
 								pixi run build                # build all packages
 								pixi run setup-ui             # download Blockly JS vendor files (first time, needs internet)
-												Add digital output block and GPIO handling

- Introduced a new Blockly block for setting digital output pins (`digitalOut`).
- Implemented the corresponding handler in Python to manage digital output actions.
- Updated dummy, GPIO, and real hardware interfaces to support digital output functionality.
- Modified the workspace configuration to include the new digital output block in the Blockly environment.
- Added potential enhancements to the README for future improvements.

											
										
										
											2026-03-09 23:08:46 +07:00
-												Add README files for blockly_app and blockly_executor; fix typo in digitalOut block

											
										
										
											2026-03-09 23:35:48 +07:00
+								pixi run executor             # Terminal 1 — start Action Server
 								pixi run app                  # Terminal 2 — start desktop GUI
-												Add digital output block and GPIO handling

- Introduced a new Blockly block for setting digital output pins (`digitalOut`).
- Implemented the corresponding handler in Python to manage digital output actions.
- Updated dummy, GPIO, and real hardware interfaces to support digital output functionality.
- Modified the workspace configuration to include the new digital output block in the Blockly environment.
- Added potential enhancements to the README for future improvements.

											
										
										
											2026-03-09 23:08:46 +07:00
+								```
-												feat: update documentation for GPIO node setup and installation on Raspberry Pi; clarify C API usage

											
										
										
											2026-03-16 05:15:50 +07:00
+								### Raspberry Pi (linux-aarch64)
 								```bash
 								pixi install                  # install ROS2 + deps via conda
 								pixi run build-gpio           # installs system deps (apt) + builds gpio_node
 								pixi run gpio-node            # start GPIO node
 								```
 								`build-gpio` automatically runs `setup-dep` which installs system libraries (`libgpiod-dev`, `liblttng-ust-dev`) via `apt`.
-												Add README files for blockly_app and blockly_executor; fix typo in digitalOut block

											
										
										
											2026-03-09 23:35:48 +07:00
+								See [docs/installation.md](docs/installation.md) for full setup and prerequisites.