pio-remote

List all active Remote Agents

$ pio remote agent list

$ pio remote agent start [[-n|--name]] [agent_name] [[-s|--share]] [example1@example.com] [[-s|--share]] [example2@example.com]

$ pio remote --agent [agent_name1] --agent [agent_name2] device list

$ pio remote --agent [agent_name] device monitor

$ pio remote --agent [agent_name] run

$ pio remote --agent [agent_name] update

$ pio remote --agent [agent_name] test

pio remote [OPTIONS]

agent
    Starts the PlatformIO Remote Agent on the host machine. This agent listens for commands from a local PlatformIO CLI, allowing remote compilation, uploading, and debugging tasks to be performed. It typically runs in the background and provides necessary drivers for connected devices.

run
    Executes a remote PlatformIO project build, upload, or both. This command functions similarly to pio run but targets a remote environment managed by an active agent. It supports all standard PlatformIO build environments and targets.

test
    Runs unit tests remotely on a connected device or host. This is useful for automated testing of embedded code in its intended environment without direct physical intervention.

monitor
    Establishes a remote serial port monitor session. It allows developers to view serial output from a remotely connected device, crucial for debugging and observing device behavior, akin to pio device monitor locally.

debug
    Initiates a remote debugging session. This command enables stepping through code, inspecting variables, and setting breakpoints on an embedded target connected to the remote agent, significantly aiding in complex problem diagnosis.

--version
    Displays the PlatformIO Core version.

--help, -h
    Shows a help message for the pio remote command or its subcommands.

pio-remote is a powerful extension of the PlatformIO ecosystem, enabling seamless remote development for embedded systems. It allows developers to compile, upload, monitor, and debug their PlatformIO projects on a remote machine or target device, often connected via a network. This is particularly useful for scenarios where the development environment cannot be directly on the target device (e.g., resource-constrained devices, or when the device is in a hard-to-reach location). The command operates by leveraging a pio remote agent running on the remote machine, which acts as an intermediary, executing commands received from the local PlatformIO CLI. This facilitates continuous integration, remote debugging, and collaborative development for IoT and embedded projects without needing direct physical access to the hardware for every operation. It significantly streamlines the workflow for distributed teams and complex deployment scenarios.

pio-remote requires an active pio remote agent running on the remote machine. Network connectivity between the local machine and the remote agent is essential. Security considerations are paramount, as the agent can execute commands on the remote system; ensure secure network configurations (e.g., SSH tunnels, firewalls). The performance of remote operations can be affected by network latency and bandwidth.

The typical workflow involves first starting the remote agent on the target machine using pio remote agent start. Once the agent is running and accessible from your local network, you can then use pio remote run, pio remote test, pio remote monitor, or pio remote debug from your local machine, passing in the relevant project configuration and options. The agent acts as a proxy, executing these commands on the remote machine where the target hardware is connected.

The pio remote agent subcommand also provides actions like stop to terminate the agent, restart to restart it, and status to check its current state. These are crucial for managing the remote environment.

pio-remote was developed as a key feature within the PlatformIO ecosystem to address the growing need for efficient remote development in IoT and embedded systems. As projects became more complex and distributed, managing hardware that wasn't physically co-located with the developer became a bottleneck. Introduced to streamline workflows for CI/CD, remote debugging, and collaborative development, it quickly became an integral part of PlatformIO for professional and hobbyist developers alike, evolving with the PlatformIO Core.

pio(1), platformio(1), ssh(1)