HTTP write task

Send a request to a web API each time a command channel gets a new value.

An HTTP write task sends a request to a web API each time you write a value to a command channel. For example, a valve on a schematic can send {"open": 1} to a pump controller. If you write several values at once, the task sends only the last one.

The task has no state channels. To see the value on the server, read it back with an HTTP read task. Before you start, you need a connected HTTP server.

Request body

Each endpoint has one command channel. The task puts the channel value in the JSON body at a Pointer, with a JSON type of Number, String, or Boolean. With the pointer /setpoint, a value of 42 sends this body:

{ "setpoint": 42 }

Empty pointer -> the body is the value alone, such as 42. The endpoint cannot have other fields.
Static field -> adds a fixed value at its own pointer, such as /unit with "psi".
Generated field -> adds a new UUID or timestamp at its own pointer in each request.
Enum mapping -> for the String type, sends a label for each number, such as "open" for 1.

Create an HTTP write task

In the devices toolbar, right-click the server and select Create write task.
Click Add endpoint, then set Method (POST, PUT, or PATCH) and Path.
Set Pointer and JSON type for the channel value.
To add more body fields, click Static or Generated.
Click (Start).

The Console creates a command channel for each endpoint. For a server named “Pump controller” and the path /api/control, it creates Pump_controller_api_control_cmd and its index Pump_controller_api_control_cmd_time. To choose another name, right-click the endpoint and select Rename before you start.

Python does not create channels. Create the command channel and its index first.

import synnax as sy
from synnax import http

server = client.devices.retrieve(name="Pump controller")
cmd_time = client.channels.create(
    name="pump_setpoint_cmd_time", is_index=True, data_type=sy.DataType.TIMESTAMP
)
cmd = client.channels.create(
    name="pump_setpoint_cmd", index=cmd_time.key, data_type=sy.DataType.FLOAT64
)

task = http.WriteTask(
    name="Pump controller write",
    device=server.key,
    endpoints=[
        http.WriteEndpoint(
            method="POST",
            path="/api/control",
            channel=http.ChannelField(pointer="/setpoint", channel=cmd.key),
            fields=[http.StaticWriteField(pointer="/unit", value="psi")],
        )
    ],
)
client.tasks.configure(task)
task.start()

TypeScript does not create channels. Create the command channel and its index first.

import { http } from "@synnaxlabs/client";

const [server] = await client.devices.retrieve({ names: ["Pump controller"] });
const cmdTime = await client.channels.create({
  name: "pump_setpoint_cmd_time",
  isIndex: true,
  dataType: "timestamp",
});
const cmd = await client.channels.create({
  name: "pump_setpoint_cmd",
  index: cmdTime.key,
  dataType: "float64",
});

const task = await client.tasks.create({
  name: "Pump controller write",
  rack: server.rack,
  type: "http_write",
  config: http.writeConfigZ.parse({
    device: server.key,
    endpoints: [
      {
        method: "POST",
        path: "/api/control",
        channel: { pointer: "/setpoint", channel: cmd.key },
        fields: [
          { type: "static", pointer: "/unit", jsonType: "string", value: "psi" },
        ],
      },
    ],
  }),
});
await task.start();

The HTTP write task has one option, Auto start (auto_start), which starts the task each time the Driver starts.

Endpoint reference

Each table shows the Console label of a setting, with its Python field under it. An endpoint has these settings:

Setting	Default	Notes
Method `method`	`POST`	`POST`, `PUT`, or `PATCH` in the Console.
Path `path`		Added to the base address of the server.
Query parameters `query_params`	None	A list of `{parameter, value}`.
Headers `headers`	None	A list of `{name, value}`.
`disabled`	`false`	Leaves the endpoint out of the task.

The channel value has these settings:

Setting	Default	Notes
Pointer `pointer`	Empty	Where the value goes in the body.
JSON type `json_type`	Number	Number, String, or Boolean. Not for timestamps.
Data type `data_type`	`float64`	Used only when the Console creates the channel.
Time format `time_format`	`iso8601`	For a `timestamp` channel.
Enum mapping `enum_values`	None	String type only. Maps numbers to labels.
`channel`		The command channel. The Console creates it for you.

An additional field is static or generated:

Type	Fields
Static	`pointer`, `value`. The value goes into the body as you give it.
Generated	`pointer`, `generator` (`uuid` or `timestamp`), `time_format` for timestamps.

Troubleshooting

... returned ...: ...
Cause
The server rejected the request. The description shows the status code and the response body. The task tries again after a temporary error, such as 408, 429, or a 5xx code.
Fix
Check the path, the body fields, and the authentication of the server.
Pointer ... is already used by another field
Cause
Two fields in the body use the same pointer.
Fix
Give each field its own pointer.

For other problems, see Troubleshoot hardware.

Read task

Next in LabJack

Configure a device