API Reference

Updated: 6/28/2025 Words: 0 words Reading time: 0 minutes

User devices communicate seamlessly with the platform through Web API. The following documentation details all API interfaces supported by the platform and their functions.

Hardware Operation Execution API: POST /hardware/operation

• Description: Hardware operation API is used to directly control peripherals.
• Request Body Format
  • Uses JSON format for data encapsulation and transmission

{
  "event": "...",  /* Hardware operation type, options: now/schedule/trigger. */
  "actions": [
    [hardware_operation_1], [hardware_operation_2], ..   /* One or more hardware operations */
  ],
  "return": [...]    /* Optional, send operation results to specified address */
}

• Return values vary based on different request bodies, please refer to the explanations below.

Hardware Operation Types

Immediate Execution Event (now)

When the platform receives an HTTP request with event as "now", it will immediately execute hardware operations in sequence. Format as follows:

{
  "event":"now",                             /* Required */
  "cycle": repeat_count,                     /* Optional */
  "actions": [[hardware_operation_1], [hardware_operation_2], ...] /* Required */
}

Parameter	Description
event	now event, hardware operations defined in actions will be executed immediately.
cycle	Repeat count, this parameter value must be a positive integer. Hardware operations will be repeated for this number of times.
actions	Hardware operations.

Note

Please replace the IP address in the examples below with the correct address.

Example: The following example will toggle the state of the green LED on the platform, and will execute immediately when the platform receives this request.

powershell

Invoke-WebRequest -Uri "http://192.168.4.1/hardware/operation" -Method Post -ContentType "application/json" -Body '{
    "event": "now",
    "actions": [["gpio", "led", "output", 2]]
}'

curl

curl --location --request POST "192.168.4.1/hardware/operation" --header 'Content-Type: application/json' --data-raw '{
    "event":"now",
    "actions": [["gpio", "led", "output",2]]
  }'

Scheduled Execution Event (schedule)

When the platform receives an HTTP request with event as "schedule", the platform will execute hardware operations in sequence when the time requirements in the request are met. Format as follows:

{
  "event":"schedule",                        /* Required */
  "interval":repeat_interval,                /* At least one of interval and start must be filled */
  "start":start_time,
  "repeat":event_count,                      /* Optional, number of times the event repeats at interval */
  "cycle": repeat_count,                     /* Optional */
  "actions": [[hardware_operation_1], [hardware_operation_2], ...] /* Required */
}

Parameter	Description
event	schedule event, executes when time requirements are met.
interval	Repeat interval, must have time unit, currently supports: 's'(seconds), 'm'(minutes), 'h'(hours) and 'd'(days)
start	Start time, "YYYY/MM/DD HH:MM:SS" (e.g.: "2020/11/28 15:30:0") or "YYYY/MM/DDTHH:MM:SS" (ISO 8601 standard)
repeat	Event count, if this parameter is not in the request, the event will execute continuously at repeat intervals. If 0 or positive integer, after the first execution ends, it will execute this many more times.
cycle	Same as above.
actions	Same as above.

Example: The following example will toggle the state of the green LED on the platform every 1 minute starting from 2:00 PM on January 1, 2024.

powershell

Invoke-WebRequest -Uri "192.168.4.1/hardware/operation" -Method Post -Headers "Content-Type: application/json" -Body '{
    "event":"schedule",
    "start":"2024/1/1T14:00:00",
    "interval":"1m",
    "actions": [["gpio", "led", "output",2]]
  }'

curl

curl --location --request POST "192.168.4.1/hardware/operation" --header 'Content-Type: application/json' --data-raw '{
    "event":"schedule",
    "start":"2024/1/1T14:00:00",
    "interval":"1m",
    "actions": [["gpio", "led", "output",2]]
  }'

Pin Trigger Execution Event (trigger)

When the platform receives an HTTP request with event as "pinstate", this event defines that hardware operations will be triggered when the voltage of a specified pin changes. Changes include rising edge, falling edge, or any voltage change. Format as follows:

{
  "event": "pinstate",                           /* Required */
  "pin": pin_number,                             /* Required */
  "trigger": trigger_condition,                  /* Required */
  "debouce": debounce_milliseconds,              /* Optional */
  "cycle": repeat_count,                         /* Optional */
  "actions": [[hardware_operation_1], [hardware_operation_2], ...],    /* Optional */
}

Parameter	Description
event	pinstate event, executes hardware operation commands when specified pin meets certain signal conditions.
pin	Pin number. Valid values are numbers 0-19 representing header pins, string "left" representing left button, or string "right" representing right button.
trigger	Trigger condition, supports: change/rising/falling, change triggers on pin voltage change, rising triggers on pin rising edge, falling triggers on pin falling edge.
debounce	Debounce millisecond value, bouncing causes signals to change rapidly multiple times in a short period, being mistaken for multiple triggers. During this time period, no matter how many times the signal meets trigger conditions, it will only trigger once.
cycle	Same as above.
actions	Same as above.

Note

Please note that for parameter pin, if header pin is a number, no quotes are needed, for example: "pin": 10 or "pin": 3

While left button and right button are strings, quotes are needed, for example: "pin":"left" or "pin":"right"

Example: The following example will wait for the right button on the platform to be pressed, and when pressed, will toggle the state of the green LED.

powershell

Invoke-WebRequest -Uri "192.168.4.1/hardware/operation" -Method Post -Headers "Content-Type: application/json" -Body '{
    "event":"pinstate",
    "pin": "right",
    "trigger": "falling",
    "debounce": 400,
    "actions": [["gpio", "led", "output",2]]
  }'

curl

curl --location --request POST "192.168.4.1/hardware/operation" --header 'Content-Type: application/json' --data-raw '{
    "event":"pinstate",
    "pin": "right",
    "trigger": "falling",
    "debounce": 400,
    "actions": [["gpio", "led", "output",2]]
  }'

Result Return

After the platform executes hardware operations, in addition to HTTP returns, you can choose to send results to specified addresses. This feature can be used to save data to Micro SD card or send to specified servers. This feature can be combined with scheduled events to achieve data collection.

Save Results to Micro SD Card

• After hardware operations are executed, the platform will save results to specified files in the user folder on the Micro SD card. This file records not only hardware operation results but also the specific time when the hardware operation occurred, for later data analysis use.
• Format:

["file", filename]

Example: The following example will toggle the state of the green LED on the platform every 10 seconds and write the results to /user/output.txt on the Micro card.

powershell

Invoke-WebRequest -Uri "192.168.4.1/hardware/operation" -Method Post -ContentType "application/json" -Body '{
    "event":"schedule",
    "interval":"10s",
    "actions": [["gpio", "led", "output",2]]
  }'

curl

curl --location --request POST "192.168.4.1/hardware/operation" --header 'Content-Type: application/json' --data-raw '{
    "event":"schedule",
    "interval":"10s",
    "actions": [["gpio", "led", "output",2]]
  }'