Working with Atom Linux commands

This article describes the main API commands that allow you to interact with Linux systems through the admin panel. With these commands, you can send, receive, delete, and view the history of commands for Atoms.

How to get data

Request address

To get the data, use the address: https://<server_address>/backend/api.php

List of commands

  • cmd=atom_get_all — get a list of sent commands
  • cmd=atom_get_commands — get a list of command templates
  • cmd=atom_create_command — send a Linux command
  • cmd=atom_delete_command — delete a Linux command
  • node — the number of the node where the command should be executed
     

Get the list of sent Linux commands (command history)

This command allows you to retrieve a list of all commands that have been sent to the Atom. The history includes the Atom identifier, the command that was sent, and its execution status.
Method: GET

Request parameters

  • cmd=atom_get_all — command for retrieving history
  • ident — unique Atom identifier (for example, b0:44:6t:0d:a9:04)

Request example

https://<server_address>/backend/api.php?cmd=atom_get_all&ident=b0:44:6t:0d:a9:04&node=1
Response example
[
  {
    "id": 27899,
    "agent_id": null,
    "ident": "8v:f5:8c:01:13:70",
    "script": "ls /root/",
    "processed": null,
    "ts": 1712138610,
    "result": null
  }
]
 

Get the list of Linux command templates

This command allows you to retrieve a list of Linux command templates that can be used to send to an Atom. Templates contain a description and the command that will be executed on the device.
Method: GET

Request parameters

  • cmd=atom_get_commands — command for retrieving command templates
  • ident — unique Atom identifier (for example, 80:c5:80:01:68:08)

Request example

https://<server_address>/backend/api.php?cmd=atom_get_commands&ident=80:c5:80:01:68:08
Response example
[
  {
    "id": 36,
    "command_name": "Video List",
    "description": null,
    "command": "ls -lsh /video/*.avi"
  }
]
 

Send a Linux command

This command allows you to send a Linux command to the Atom. The command will be added to the queue and executed on the device.
Method: POST

Request parameters

  • cmd=atom_create_command — command for creating a new command
  • ident — unique Atom identifier
  • script — script command (optional)

Request example

https://<server_address>/backend/api.php?cmd=atom_create_command&ident=b1:42:67:00:00:fd
Response example
27917 (ID of the command added to the queue)
 

Delete a Linux command

If a command has not yet been executed, it can be removed from the queue using this method. Deletion is possible only before the command has been processed.
Method: GET

Request parameters

  • cmd=atom_delete_command — command for deletion
  • ident— unique Atom identifier
  • command_id — ID of the command to delete

Request example

https://<server_address>/backend/api.php?cmd=atom_delete_command&ident=b0:44:6f:0d:av:88&command_id=27921
Response example
"Success delete"
 

API error codes

  • 400 Bad request — invalid data format or a required parameter is missing.
    Possible messages:
  • {"error": "Missing ident param"} — Atom identifier is missing
  • {"error": "Command already processed"} — the command has already been executed
  • {"error": "Unknown macro: {Unknown macro}"} — unknown macro command
  • 500 Internal server error — internal server error
 

Interaction with commands in the interface

In the PILOT interface, interaction with Atoms takes place through the admin panel tab "Autoconductor → Buses", where the "Interact" command is available.
Through this function you can:
  • Send commands (Linux commands) to the Atom
  • View the list of available commands (templates)
  • Display the history of all sent commands
  • Access the result of each executed command