# ARChemist Code

This repository contains the ROS/catkin workspace and configuration files used to run an ARChemist-based autonomous laboratory workflow. The code links a workflow manager, robot/station handlers, recipe files, and device-specific ROS drivers so that batches of samples can be moved through a sequence of laboratory stations.

In the supplied configuration, the workflow is set up for an algae/autonomous formulation screening system using:

- a KUKA KMR/LBR iiwa mobile manipulator,
- a Chemspeed FLEX liquid-handling station,
- a Lightbox colourimetry/imaging station,
- input and output stations,
- YAML recipe files for batch processing,
- MongoDB-backed workflow state persistence,
- ROS messages and drivers for supported laboratory devices.

> **Important:** This code controls laboratory automation hardware. Do not run it on live equipment without confirming station positions, robot frames, safety interlocks, emergency stops, device communication settings, and recipe contents.

---

## Repository contents

```text
ARChemist Code/
├── archemist_ws/                 # ROS/catkin workspace
│   ├── src/                      # Source packages
│   │   ├── archemist/            # Main ARChemist workflow package
│   │   ├── chemspeed_flex_driver/
│   │   ├── colorimetry_msgs/
│   │   ├── fisherbrand_pps4102_balance/
│   │   ├── franka_msgs_archemist/
│   │   ├── ika_plate_rct_digital/
│   │   ├── kern_pcb_balance/
│   │   ├── kmriiwa_chemist_msgs/
│   │   ├── mettler_toledo_quantos_q2/
│   │   └── pi4_peristaltic_pump/
│   ├── build/                    # Existing catkin build output
│   ├── devel/                    # Existing catkin development output
│   └── server_settings.yaml      # Workflow server settings
└── Recipies/                     # Exported recipe/state JSON and YAML files
    ├── batches.json
    ├── materials.json
    ├── optimisation.json
    ├── recipes.json
    ├── robots.json
    ├── state.json
    ├── stations.json
    └── recipes/                  # Timestamped algae bot recipe YAML files
```

Note that the folder is named `Recipies` in the uploaded archive. This README keeps that spelling when referring to the existing path.

---

## Main package: `archemist`

The `archemist` package contains the workflow logic used to construct, schedule, monitor, and execute laboratory workflows.

Key files and folders:

```text
archemist/
├── msg/HandlerBusMessage.msg
├── scripts/
│   ├── archemist_cli.py          # Interactive CLI for start/pause/batch/charging commands
│   ├── workflow_server.py        # Main workflow server using recipe-file watching and ZMQ commands
│   ├── run_recipe.py             # Example continuous recipe runner
│   ├── launch_handlers.py        # Handler launcher
│   ├── launch_workflow_manager.py
│   ├── resetDb.py                # MongoDB reset helper
│   ├── config_files/             # Workflow configuration YAML files
│   ├── recipes/                  # Test/example recipe YAML files
│   └── server_settings.yaml      # Server settings used by workflow_server.py
├── src/archemist/
│   ├── persistence/              # MongoDB/YAML persistence and recipe watchdog logic
│   ├── processing/               # Workflow manager, scheduler, handlers, state machines
│   ├── state/                    # State models for batches, recipes, robots, stations, materials
│   ├── util/                     # Location and job helper objects
│   └── visualisation/
└── tests/                        # Unit and process tests
```

The workflow manager reads a workflow configuration file, constructs the runtime state, watches for recipe files, and queues station/robot operations according to the recipe state machine.

---

## Included ROS packages

| Package | Purpose |
|---|---|
| `archemist` | Main workflow manager, scheduler, handlers, state models, persistence layer, and CLI/server scripts. |
| `chemspeed_flex_driver` | ROS driver for the Chemspeed FLEX robot/liquid-handling station. |
| `chemspeed_flex_msgs` | ROS message definitions for Chemspeed FLEX commands and status. |
| `colorimetry_msgs` | ROS messages for Lightbox/colourimetry commands and results. |
| `fisherbrand_pps4102_balance_driver` | ROS driver for Fisher Scientific PPS4102 balance communication over RS232/USB. |
| `fisherbrand_pps4102_balance_msgs` | ROS messages for Fisher balance commands/readings. |
| `franka_msgs_archemist` | Message definitions for Franka Panda task/status integration. |
| `ika_plate_rct_digital_driver` | ROS driver for IKA RCT Digital hotplate/stirrer communication. |
| `ika_plate_rct_digital_msgs` | ROS messages for IKA commands/readings. |
| `kern_pcb_balance_driver` | ROS driver for KERN PCB balance communication. |
| `kern_pcb_balance_msgs` | ROS messages for KERN balance commands/readings. |
| `kmriiwa_chemist_msgs` | ROS messages for KMR/LBR navigation, arm commands, task status, and task updates. |
| `mettler_toledo_quantos_q2_driver` | ROS driver for Mettler Toledo Quantos Q2 solid dispensing. |
| `mettler_toledo_quantos_q2_msgs` | ROS messages for Quantos commands, samples, and responses. |
| `pi4_peristaltic_pump_driver` | ROS driver for a custom Raspberry Pi/peristaltic pump liquid dispenser. |
| `pi4_peristaltic_pump_msgs` | ROS messages for the custom peristaltic pump dispenser. |

---

## Software requirements

The existing package README lists the following Python/runtime requirements:

- ROS with catkin build support
- Python 3
- MongoDB
- `pymongo`
- `transitions`
- `multipledispatch`
- `pyzmq`
- `PyInquirer`

Typical installation commands are:

```bash
sudo apt update
sudo apt install mongodb

python3 -m pip install pymongo transitions multipledispatch pyzmq PyInquirer
```

Depending on the ROS distribution and operating system, additional ROS message/build dependencies may also be required, including:

```bash
sudo apt install ros-$ROS_DISTRO-std-msgs ros-$ROS_DISTRO-geometry-msgs ros-$ROS_DISTRO-sensor-msgs
```

---

## Building the workspace

From the workspace root:

```bash
cd archemist_ws
catkin_make
source devel/setup.bash
```

The uploaded archive already contains `build/` and `devel/` directories. For a clean rebuild, remove them first:

```bash
cd archemist_ws
rm -rf build devel
catkin_make
source devel/setup.bash
```

For a fresh repository, `build/`, `devel/`, `.DS_Store`, `__pycache__/`, and generated Python bytecode files should normally be excluded from version control.

---

## Workflow configuration

Workflow configuration files are stored in:

```text
archemist_ws/src/archemist/scripts/config_files/
```

Important examples include:

| File | Description |
|---|---|
| `algae_bot_config_file.yaml` | Main algae bot workflow configuration with KUKA, input station, Chemspeed FLEX, Lightbox, and output station. |
| `chemspeed_testing_config_file.yaml` | Chemspeed-specific testing configuration. |
| `lightbox_testing_config_file.yaml` | Lightbox-specific testing configuration. |
| `dif_demo_testing_config_file.yaml` | Demonstration/testing configuration. |
| `solubility_screening_config.yaml` | Solubility-screening configuration. |

The algae bot configuration defines:

- robots under `workflow.Robots`,
- materials under `workflow.Materials`,
- station definitions under `workflow.Stations`,
- station classes such as `InputStation`, `ChemSpeedFlexStation`, `LightBoxStation`, and `OutputStation`,
- station state machines such as `InputStationSm`, `ChemSpeedRackProcessingSm`, `LightBoxSM`, and `OutputStationSm`,
- station locations using KMR navigation node IDs and graph IDs.

---

## Recipe files

Recipe files are YAML documents that define the sequence of station operations for a batch. Example recipes are stored in:

```text
archemist_ws/src/archemist/scripts/recipes/
```

The main algae test recipe is:

```text
algae_bot_test_recipe.yaml
```

A typical recipe contains:

- recipe name and ID,
- required materials,
- station operations,
- operation descriptors and output descriptors,
- a workflow state machine defining `onSuccess` and `onFail` transitions.

Example operation sequence in the algae workflow:

```text
InputStation pickup
→ Chemspeed FLEX CSV liquid-handling job
→ Lightbox vial processing / colourimetry
→ OutputStation placement
→ End
```

The exported `Recipies/recipes/` folder contains timestamped algae bot recipes from previous workflow runs.

---

## Server settings

The workflow server reads settings from:

```text
archemist_ws/src/archemist/scripts/server_settings.yaml
```

or the equivalent file in the workspace root.

Important fields include:

```yaml
workflow_dir_path: 'C:\Users\ACL_KUKA2\m_algae_bot_workflow'
db_name: 'algae_bot_test3'
batch_addition:
  location:
    node_id: 25
    graph_id: 1
    frame_name: '/InputStation'
  num_vials: 6
recipe_loop_mode: False
auto_batch_addition: False
```

Before running the workflow server, update `workflow_dir_path` so that it points to the active workflow directory on the target machine. That directory should contain:

```text
config_files/workflow_config.yaml
recipes/
```

The server watches the `recipes/` directory and queues new recipe YAML files as they appear.

---

## Running the workflow server

From the `scripts` directory:

```bash
cd archemist_ws/src/archemist/scripts
python3 workflow_server.py
```

The server will:

1. load `server_settings.yaml`,
2. construct the workflow state from `workflow_config.yaml`,
3. connect to the configured MongoDB database,
4. start watching the configured recipe directory,
5. listen for local ZMQ commands on `tcp://127.0.0.1:5555`.

In a second terminal, the CLI can be launched with:

```bash
cd archemist_ws/src/archemist/scripts
python3 archemist_cli.py
```

The CLI provides the following commands:

- `Start/Resume`
- `Pause`
- `Add clean batch`
- `Start charging`
- `Stop charging`
- `Resume LBR app`
- `Terminate`

---

## Running a test recipe directly

The `run_recipe.py` script provides an example of loading a workflow configuration and repeatedly queuing the algae bot test recipe:

```bash
cd archemist_ws/src/archemist/scripts
python3 run_recipe.py
```

By default, it uses:

```python
config_file_name = 'algae_bot_config_file.yaml'
recipe_file_name = 'algae_bot_test_recipe.yaml'
db_name = 'algae_bot_test'
clean_batch_location = Location(25, 1, '/InputStation')
```

This should be treated as an example/test runner. Check all recipe contents and station locations before using it with real hardware.

---

## Resetting the database

A helper script is included:

```text
archemist_ws/src/archemist/scripts/resetDb.py
```

Use this carefully. Resetting the database will remove persisted workflow state and may affect recovery from interrupted runs.

---

## Hardware driver notes

Several included packages provide ROS nodes for individual hardware devices. Driver packages commonly contain:

```text
<driver_package>/launch/
<driver_package>/nodes/
<driver_package>/src/<driver_package>/
```

For example, the Chemspeed FLEX driver includes:

```text
chemspeed_flex_driver/chemspeed_flex_driver/
├── launch/chemspeed_flex_driver.launch
├── nodes/chemspeed_flex_node
└── src/chemspeed_flex_driver/
    ├── chemspeed_flex_driver.py
    └── ros_chemspeed_flex_driver.py
```

Launch files are provided for several hardware drivers, including the Chemspeed FLEX, Fisher balance, IKA hotplate, KERN balance, Quantos Q2, and peristaltic pump packages.

---

## Safety checklist before live operation

Before running on physical equipment, check the following:

- Emergency stop and safety systems are functional.
- KUKA/KMR navigation maps, node IDs, graph IDs, and station frames match the current laboratory layout.
- The LBR application is running and ready to receive tasks.
- Chemspeed FLEX task files, CSV formats, deck positions, racks, and door/interlock logic are correct.
- Lightbox camera, lighting, trigger topic, and output handling are functioning.
- Input/output station positions are physically clear.
- Recipe files contain safe volumes, materials, and station order.
- MongoDB contains the intended workflow state, or has been reset deliberately.
- No stale recipes are left in the watched recipe directory unless they should be queued.
- Operators are present and able to intervene during testing.

---

## Development notes

Recommended cleanup before publishing or archiving as a repository:

```bash
find . -name '.DS_Store' -delete
find . -name '._*' -delete
find . -name '__pycache__' -type d -prune -exec rm -rf {} +
find . -name '*.pyc' -delete
rm -rf archemist_ws/build archemist_ws/devel
```

Suggested `.gitignore` entries:

```gitignore
build/
devel/
install/
*.pyc
__pycache__/
.DS_Store
._*
.vscode/
```

---

