Skip to main content

📄 Writing the README for a Device Plugin

Each plugin must include a README.md file written for lab users and integrators, not developers. It should provide practical, clear instructions on how to set up and use the plugin — based on the actions it supports.

Avoid repeating structured metadata like vendor, model, connection type, capabilities, or config fields — those are defined in automation.json.

✅ Required Sections​

1. What This Plugin Connects To​

Start with a simple, human-friendly description of what machine this plugin works with, and what data it exchanges.

📌 Example:

This plugin connects to the Sysmex XP-300 hematology analyzer via serial cable. It receives test results from the analyzer and uploads them automatically into Automation.

2. How to Connect the Machine​

Clearly explain:

  • The physical connection required (USB-to-Serial, LAN, etc.)
  • How to select or configure the connection in Automation
  • Any default parameters (baud rate, parity, etc.)

📌 Example:

  1. Connect the analyzer to your PC using a USB-to-Serial cable.
  2. In Automation, go to Connections → Add Machine, and select COM3 (or the appropriate port).
  3. Use the default settings: 9600 baud, 8 data bits, no parity, 1 stop bit.
  4. Click Connect to establish the link.

3. How Results Are Captured (if produce capability is declared)​

Explain what triggers result transmission and what users should see.

📌 Example:

As soon as a test is completed, the analyzer sends the result. The plugin captures it automatically and uploads a structured result to the Results tab in Automation.

4. How to Set Up Automatic Result Sending (if required)​

Some analyzers must be configured to automatically send results. Explain how to do that on the machine interface.

📌 Example:

On the analyzer:

  • Go to Menu → Settings → Interface
  • Set mode to “Host” and enable “Auto Send”

5. How to Receive Test Requests (if receive capability is declared)​

Describe how Automation sends orders to the analyzer, and what settings must be enabled for it to work.

📌 Example:

This plugin supports sending test requests to the analyzer.

To enable bidirectional mode:

  1. Ensure the analyzer is on the same LAN as the computer.
  2. In Automation, provide the analyzer's IP and listening port.
  3. On the analyzer, enable remote commands: Settings → Network → Accept Orders.

6. What to Expect After Setup​

Help the user understand what happens once everything is working.

📌 Example:

Once connected:

  • The plugin status shows Connected
  • New test results appear in the Results tab
  • If test requests are enabled, orders are automatically sent when a sample is logged

7. Troubleshooting Tips​

Cover common issues with suggested solutions.

📌 Example:

  • No data received? Check that the analyzer is set to auto-send results.
  • COM port not listed? Try replugging the USB-to-Serial cable and restart Automation.
  • Order not received? Verify that the analyzer’s IP matches the one entered in Automation.

🧾 Template​

# Plugin: Sysmex XP-300

## What It Does
Connects to the Sysmex XP-300 hematology analyzer and captures test results via serial port.

## How to Connect
1. Plug the analyzer into your PC using a USB-to-Serial cable
2. In Automation, choose the correct COM port (e.g., COM3)
3. Use the default serial settings (9600 baud, 8N1)
4. Click "Connect" in Automation

## How Results Are Captured
Test results are sent automatically after each test.  
Automation receives and parses them into structured reports instantly.

## How to Set Up Auto Send
On the analyzer:
- Go to `Menu → Settings → Interface`
- Enable “Auto Send Results”

## How to Receive Test Requests
1. Enable “Remote Orders” on the analyzer
2. Make sure the analyzer IP and port are correctly configured in Automation
3. Orders from Automation will be sent automatically when a test is logged

## What to Expect
- Status shows “Connected” in Automation
- Test results show in the Results tab within seconds
- Requests (if enabled) are sent and confirmed

## Troubleshooting
- No results? Confirm analyzer is in host mode and auto-send is on
- Serial port not found? Check drivers or try a different cable
- Orders not received? Check the analyzer’s IP and firewall settings