Sending Requests

pycom listens for incoming TCP connections on port 5000. All requests are JSON payloads sent over a raw TCP socket, encoded in UTF-8. Any application that can open a TCP connection and send a JSON string can communicate with LA⁴.

Request base structure

Every request must include the following fields that identify the sender:

Field	Type	Description
id	string	Unique identifier for the sender
name	string	Human-readable name for the sender
ip	string	IP address of the sender
port	number	Port the sender is listening on
version	string	a version number for your application. This is irrelevant for your integration but necessary to specify.
coordinator	boolean	Set this to true if the sender is a coordinator (PC application managing LA4)

Additional fields are required depending on the request type. The most used is the command type which we describe next.

Composing a heartbeat

A heartbeat is a base request with no extra fields. It tells pycom that your application is still online. Your application should send one every 5 seconds. If pycom does not receive a heartbeat for 15 seconds, it considers your application offline and the scanning of the search for a coordinator restarts by scanning all other IPs in the subnet.

// example of heartbeat sent to pycom
{
    "id": "7756f193",
    "name": "My LightArray integration",
    "ip": "192.168.0.100",
    "port": 5000,
    "version": "0.1.0",
    "coordinator": true
}

Composing a command

A command request instructs a node to execute a shell command. In addition to the base request fields, include the following:

Field	Type	Description
type_	string	Must be "cmd" to identify this as a command request
command	string	The shell command for the node to execute

How to send a request

Sending any request — whether a heartbeat or a command — follows the same steps:

1. Open a TCP connection to LA⁴ at its IP address and port (e.g. when static IP topology is used 192.168.0.23:5000).
2. Serialize your payload as a JSON string encoded in UTF-8.
3. Send the bytes over the socket.
4. Close the connection.

// command example for turning on the model light and the fans
{
  "command": "echo \"MODEL_LIGHT,100\\nLED_FAN,1\" > /home/rigsters/la4_sequence.csv && boardiocli uSeq && boardiocli runSeq",
  "type_": "cmd",
  "id": "31548ca2",
  "name": "My PC App",
  "ip": "192.168.0.100",
  "port": 5000,
  "version": "0.1.0",
  "coordinator": true
}

Python

import socket
import json

NODE_IP = "192.168.0.100"
NODE_PORT = 5000

payload = {
    "command": "echo \"MODEL_LIGHT,100\\nLED_FAN,1\" > /home/rigsters/la4_sequence.csv && boardiocli uSeq && boardiocli runSeq",
    "type_": "cmd",
    "id": "31548ca2",
    "name": "My PC App",
    "ip": "192.168.0.100",
    "port": 5000,
    "version": "0.1.0",
    "coordinator": True,
}

with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
    s.connect((NODE_IP, NODE_PORT))
    s.send(json.dumps(payload).encode("utf-8"))

C#

using System.Net.Sockets;
using System.Text;
using System.Text.Json;

var payload = new
{
    command = "echo \"MODEL_LIGHT,100\\nLED_FAN,1\" > /home/rigsters/la4_sequence.csv && boardiocli uSeq && boardiocli runSeq",
    type_ = "cmd",
    id = "31548ca2",
    name = "My PC App",
    ip = "192.168.0.100",
    port = 5000,
    version = "0.1.0",
    coordinator = true,
};

using var client = new TcpClient("192.168.0.23", 5000);
using var stream = client.GetStream();
var json = JsonSerializer.Serialize(payload);
await stream.WriteAsync(Encoding.UTF8.GetBytes(json));

Receiving a response

pycom does not reply on the same TCP connection. When the node processes a command, it opens a new TCP connection back to the IP it observed from your connection and the port you specified in the request payload, delivering the output as a JSON payload with type_: "output".

To receive responses, your application must run its own TCP listener on the port specified in your requests. Read more in the next page.