How to Utilize the `pio remote` Command (with examples)
The pio remote command, a component of the PlatformIO Remote Development toolkit, enables developers to work efficiently on embedded systems development projects from remote locations. This powerful command mirrors the behavior of its locally-operating counterpart, pio, extending capabilities to connect and manage devices and environments remotely. With functionalities ranging from listing remote agents to connecting with devices and running tests, pio remote optimizes collaborative development and field testing without the need for physical presence.
Use case 1: List all active Remote Agents
Code:
pio remote agent list
Motivation:
Imagine you’re coordinating a distributed development team where each member runs tests on different parts of a project. Knowing which remote agents are active allows you to effectively manage resources and ensure everyone is connected and productive without physically being near each host machine.
Explanation:
pio remote: Invokes the remote development context.agent list: This argument is used to query and display a list of all currently active remote agents detectable in your environment. It gathers information necessary for effective distribution of tasks among the team.
Example Output:
1. Agent Name: Home-Lab
Status: Online
Owner: example1@example.com
2. Agent Name: Office-PC
Status: Online
Owner: example2@example.com
Use case 2: Start a new Remote Agent with a specific name and share it with friends
Code:
pio remote agent start --name agent_name --share example1@example.com --share example2@example.com
Motivation:
This use case is perfect when setting up a new development environment that needs to be shared among team members or friends, perhaps for collective debugging or collaborative development. Sharing the agent allows precise and unfettered collaboration by enabling instant access to the configured remote environment.
Explanation:
pio remote agent start: This starts a new remote agent on your current machine, thereby enabling it for remote operations.--name agent_name: Assign a specific name to your remote agent for easy identification by collaborators.--share example1@example.com --share example2@example.com: These options allow you to specify email addresses of individuals you want to share the access with, making it possible for multiple collaborators to engage with the remote agent seamlessly.
Example Output:
Agent named "agent_name" started.
Shared with: example1@example.com, example2@example.com.
Use case 3: List devices from specified Agents
Code:
pio remote --agent agent_name1 --agent agent_name2 device list
Motivation:
While working on a project with several remote environments, each linked to different hardware devices, you need to keep track of which devices are connected to which agents. This command helps you quickly locate and deploy updates or run tests on the appropriate devices without confusion.
Explanation:
pio remote: This initiates PlatformIO’s remote functionality.--agent agent_name1 --agent agent_name2: These flags specify which agents’ devices you are interested in listing, allowing precise selection or exclusion based on your project needs.device list: The command to compile and show a list of connected devices associated with the mentioned agents.
Example Output:
Agent: agent_name1
- Device: Arduino Uno
Status: Connected
- Device: Raspberry Pi Pico
Status: Connected
Agent: agent_name2
- Device: ESP32
Status: Connected
Use case 4: Connect to the serial port of a remote device
Code:
pio remote --agent agent_name device monitor
Motivation:
Serial monitoring is crucial for embedded systems when debugging and developing. It helps log outputs and diagnose issues effectively. This command is especially useful when you’re troubleshooting code running on remote hardware, ensuring that you can monitor and view logs in real-time without being physically present.
Explanation:
pio remote: Signals the execution of a remote command.--agent agent_name: Specifies the agent hosting the device you wish to monitor, ensuring you connect to the correct unit.device monitor: Opens a monitoring session over a connected serial port, providing a stream of logs and data output by the device.
Example Output:
--- Terminal on /dev/ttyUSB0 | 115200 8-N-1 ---
Hello from Remote Device
Initializing...
[INFO] System started
Use case 5: Run all targets on a specified Agent
Code:
pio remote --agent agent_name run
Motivation:
Deploying and building code remotely can streamline continuous integration workflows. This command lets you effortlessly compile and deploy your entire project across an agent, ideal for environments where code needs to be built remotely due to differing library dependencies or hardware constraints.
Explanation:
pio remote: Denotes the usage of a remote operation.--agent agent_name: Identifies which remote agent should process theruncommand.run: Executes the build process for all configured targets on the specified agent, covering all the necessary steps and dependencies required by the project.
Example Output:
Processing agent_name (platform: atmelavr; board: uno)
Verbose mode can be enabled via `-v, --verbose` option
CONFIGURATION: Link to JSON
PLATFORM: Atmel AVR (4.1.0) > ATmega328P
HARDWARE: ATMEGA328P 16MHz, 2KB RAM, 32KB Flash
...
Use case 6: Update installed core packages, development platforms and global libraries on a specific Agent
Code:
pio remote --agent agent_name update
Motivation:
Keeping the development environment up-to-date is crucial for optimal performance and security. When new updates are available for the core packages, platforms, or libraries, executing this command ensures that the remote systems stay current, preventing potential incompatibility issues or bugs due to outdated software.
Explanation:
pio remote: Starts the function for remote management.--agent agent_name: Directs the update operation to a specific agent that needs maintenance.update: Fetches the latest updates for all core packages, development platforms, and libraries on the specified remote agent.
Example Output:
Updating terrace databases...
Updating core platforms...
Updating libraries...
Platform atmelsam: @4.1.2...
Updating arduino-libraries: Added 24 new library updates.
Everything is updated.
Use case 7: Run all tests in all environments on a specific Agent
Code:
pio remote --agent agent_name test
Motivation:
Testing is a critical phase of development to ensure code quality and functionality. This command allows developers to execute comprehensive test suites across all environments configured on a specific agent, ensuring thorough validation before deployment or further development.
Explanation:
pio remote: Invokes the platform’s remote functionalities.--agent agent_name: Specifies which agent should execute the test cases.test: Performs all unit tests, integration tests, and any other specified tests across all defined environments for robust software validation.
Example Output:
Testing project in environments: nodemcuv2, uno
PASS: test/test_example.cpp
- project_spec: PASS
- src_test: PASS
Tested 2/2 environments
All tests passed!
Conclusion:
The pio remote command offers a comprehensive suite of tools that support distributed and remote development environments, facilitating enhanced collaboration and flexibility. Understanding its varied use cases allows developers to manage testing, debugging, and deployments efficiently, irrespective of physical location. By leveraging these commands, development teams can maximize productivity, optimize workflows, and ensure seamless integration into modern development pipelines.
