Commands

Commands are not related to an object on the screen but can get or set global properties or invoke system commands on the device.

Issuing commands~

Commands can be issued via the Serial commandline, telnet commandline or MQTT.

For MQTT, you can use either:

hasp/<nodename>/command topic with payload <keyword>=<parameter(s)>
hasp/<nodename>/command/<keyword> topic with payload <parameter(s)>
Leave the payload empty to get the current state without changing it.

Batch processing~

Commands can be processed in batch one after another from .cmd script files located in the flash storage of the plate.
General rules when creating .cmd batch scripts:

can contain any command
empty lines are ignored
# or // can be used for comments
space or tab in front of a command is ignored
lines starting with { are processed as jsonl payloads
lines starting with [ are processed as json payloads
other lines are processed as <command> <payload>
CR, LF or CRLF line endings allowed
UTF8 encoding is required for special characters

To start a batch script, use run command.

System scripts~

If any of the following scripts is present on the filesystem, it will be run automatically according to the rules below:

L:/boot.cmd is executed when the plate has finished (re)booting
L:/online.cmd will be executed after connection to the network was successfull
L:/offline.cmd will be executed after connection to the WiFi is lost

This makes it possible to disable or hide buttons, load a special offline page, etc. See example.

Global commands~

run~

accepted parameters: name of a .cmd or .jsonl file present on the flash filesystem of the plate. Filename must be preceeded by the / character

Run a batch script or load a jsonl page.

Example

run /script.cmd
run /pages_party_mode.jsonl

jsonl~

accepted parameters: one or more json formatted lines

Create new objects or update the properties of an existing object. When updating an existing object the obj property is not required and will be ignored.

Each line in the jsonl payload defines one object and has to be in the json format. If the payload exceeds the MQTT buffer of 2 kB it will be cut off to fit, don't send too many lines in a single payload, you can always sends multiple jsonl commands.

Example

jsonl {"obj":"btn","id":14,"x":120,"y":1,"w":30,"h":40,"text_font":"2","text":"Test","text_color":"gray","bg_opa":0,"border_width":0}

For more details see Pages and Objects.

json~

accepted parameters: json array of strings

Use the json command to send multiple commands as an array of strings in one payload.

Example

json ['page 3','backlight {"state":"ON","brightness":100}','idle off']

This command will change to page 3, turn the backlight on at ~40% brightness and reset the idle timer.

page~

accepted parameters: [1-12], prev, next or back

Switches the display to show the objects from a different page and return the page number in state/page.

Calling the page command without a parameter will return the value of the current page in state/page.

clearpage~

accepted parameters: [0-12] or all

Deletes all objects on a given page. If no page number is specified, it clears the current page. Use clearpage all to clear all objects on all pages.

To delete individual objects, you can issue the pXbY.delete command.

backlight~

accepted json keys:

state: on/off, true/false, 0/1, yes/no
brightness: 1..255

Example

backlight {"state":"on","brightness":128} sets the display to half the brightness.

Instead of a json payload, you can use a simple payload. To change the state, use either on/off, true/false, 0, yes/no. A simple integer payload of 1..255 will adjust the brightness.

Example

backlight off
backlight 200 sets the display brightness to ~80%.

moodlight~

accepted json keys:

state: on/off, true/false, 0/1, yes/no
brightness: 1..255
color or
r, g, b: 0..255

An RGB moodlight can be controlled by configuring 3 GPIO pins as type Mood Red, Mood Green and Mood blue. These leds can then be controlled together using the moodlight command.

Example

moodlight {"state":"off","color":"green"}
moodlight {"state":true,"color":"#ff00e7"}
moodlight {"color":12345}
moodlight {"state":"on","r":255,"g":0,"b":255}

The state key accepts boolean values to turn the moodlight on or off
The brightness key can be set between 1 and 255 to dim the moodlight
The color key accepts color values to set the RGB channels at once
Individual r, g and b keys can also be used to set each channel separately

Calling the moodlight command without parameters (or sending an empty payload to the hasp/<nodename>/command/moodlight topic) returns the current state:

Example

"state/moodlight" {"state":"ON","brightness":255,"color":"#ff0000","r":255,"g":0,"b":0}

The color is returned as a hexadecimal value and as individual RGB channels.

idle~

accepted parameters: off, short or long

Sets the idle state of the device and publishes the new state via a state/idle status message.

off resets the idle counter as if a touch event occurred on the device. This is helpful e.g. when you want to wake up the display when an external event has occurred, like a PIR motion sensor.

short or long sets the idle timer to the number of seconds configured in the Display Settings. You can use this to force an idle state, for example at night or when leaving the house.

Calling the idle command without a parameter will also return the current idle state short, long or off in the state/idle topic.

output[x]~

where [x] is number of the gpio pin (0-39)

accepted json keys:

state: on/off, true/false, 0/1, yes/no
val: 0..255

Changes the state GPIO pin to on or off. If the pin is configured as a LED or Serial Dimmer then the val key will control the brightness.

Note

If the GPIO is assigned to a group then objects and other GPIOs that share the same groupid will change state accordingly.

input[x]~

where [x] is number of the gpio pin (0-39)

read-only

Returns a JSON object containing the current state of the input, either on or off

Example

input4 => {"state":"on"}

System Commands~

`antiburn`~

accepted parameters: on/off, true/false, 0/1, yes/no

Start LCD anti burn-in protection.

This cycles the display to a full black, red, green, blue and white color each second to relief the tension put on each individual pixel. The cycle stops when either:

30 seconds have passed
antiburn=off is received
The screen is touched

If you're using Home Assistant, check out the automation example to make it run on a regular basis.

`calibrate`~

Start on-screen touch calibration.

You need to issue a soft reboot command to save the new calibration settings. If you do a hard reset of the device, the calibration settings will be lost.

`discovery`~

Trigger the sending of the discovery payload.

`sensors` ~

Trigger the sending of the sensor data.

`factoryreset`~

Clear the filesystem and EEPROM and reboot the device in its initial state.

Warning

There is no confirmation prompt nor an undo function!

`reboot` or `restart`~

Saves any changes in the configuration file and reboots the device.

`screenshot`~

Saves a picture of the current screen to the flash filesystem. You can retrieve it via http://<ip-address>/screenshot.bmp. This can be handy for bug reporting or documentation.

The previous screenshot is overwritten.

`service`~

Start or stop some of the processes running on the plate.

Currently supported parameters:

start
stop

Currently supported services:

http (web interface)
telnet (remote console)
console (serial console)

Example

To stop the web interface of the plate, send to topic hasp/<your_plate>/command/service the string stop http. To start the web interface of the plate, send to topic hasp/<your_plate>/command/service the string start http.

Tip

Once these services are stopped, connection is lost/not possible to the plate through them. They can be started at any time by sending service start commands in through MQTT.
It's possible to create self-built firmware binaries which have services stopped by default at boot, using customization.

`statusupdate`~

Reports the status of the MCU. The response will be posted to the state topic.

Example

"hasp/<platename>/state/statusupdate" => {
    "node": "plate01",
    "idle": "long",
    "version": "0.6.3",
    "uptime": 11027,
    "ssid": "my_network",
    "rssi": -60,
    "ip": "192.168.0.133",
    "mac": "7C:87:CE:E3:55:55",
    "heapFree": 58756,
    "heapFrag": 7,
    "core": "v4.4.1",
    "canUpdate": "false",
    "page": 1,
    "numPages": 12,
    "tftDriver": "ILI9488",
    "tftWidth": 480,
    "tftHeight": 320
}

`unzip`~

Unzip a file-packgage on the plate. You can upload uncompressed ZIP files to the flash space of your plate and unzip them locally. This is useful for cases when you need a lot of small files to be uploaded - putting them in an uncompressed zip allows to upload them in one go, and then extract them with a single command:

Example

unzip /openhasp-weathericons-day.zip

`update`~

accepted parameters: [url]
Update the firmware from the url provided. Reboots when update was successful.

Configuration Settings~

Wi-FI~

`ssid`~

Set network name of the access point to connect to.

`pass`~

Set the optional password for the access point to connect to.

MQTT~

`nodename`~

Set the nodename of the device and mqtt topic for the node to hasp/<nodename>/

`mqtthost`~

Set the IP address or nodename of the mqtt broker.

`mqttport`~

Set the port of the mqtt broker.

`mqttuser`~

Set the optional username for the mqtt broker.

`mqttpass`~

Set the optional password for the mqtt broker.

config/submodule~

You can get or set the configuration of an openHASP submodule in json format. To get the configuration, use the command config/<submodule>:

config/wifi
config/mqtt
config/http
config/mdns
config/hasp
config/gui
config/debug
config/gpio

The result will be published to hasp/<nodename>/state/config. Passwords will be omitted from the result.

To update the configuration simply issue the same command config/<submodule> with updated json payload.

Example

config/gui {"idle2":0} disable long idle (don't turn off the screen completely)
config/debug {"tele":300} set the telemetry period to 300 seconds
config/hasp {"startdim":255} to set the startup brightness to 255

Last update: 2023-12-09

Commands

Issuing commands~

Batch processing~

System scripts~

Global commands~

run~

jsonl~

json~

page~

clearpage~

backlight~

moodlight~

idle~

output[x]~

input[x]~

System Commands~

antiburn~

calibrate~

discovery~

sensors ~

factoryreset~

reboot or restart~

screenshot~

service~

statusupdate~

unzip~

update~

Configuration Settings~

Wi-FI~

ssid~

pass~

MQTT~

nodename~

mqtthost~

mqttport~

mqttuser~

mqttpass~

config/submodule~

`antiburn`~

`calibrate`~

`discovery`~

`sensors` ~

`factoryreset`~

`reboot` or `restart`~

`screenshot`~

`service`~

`statusupdate`~

`unzip`~

`update`~

`ssid`~

`pass`~

`nodename`~

`mqtthost`~

`mqttport`~

`mqttuser`~

`mqttpass`~