Scripting with p44Script

This page provides an overview of the programming language p44script, which is used in the P44 products to configure and extend functionality. It mainly deals with the concepts in and around p44script.

For a detailed description of the syntax and functions available in p44script, please refer to the p44script short reference, which is also available offline in every P44 device (see link at the bottom right of script input fields).

Where can p44script scripts be used?

---

The p44script programming language is a so-called "embedded" scripting language that can add functionality via scripts in various places in the environment in which it is embedded. In principle, p44script can be integrated into any C++ project if the p44utils library is used.

In this section, however, the different locations for the use of p44script ** within a P44-DSB or P44-LC device will be shown.

Script contexts

Because the scripts can run at different locations in the system, there are also different so-called script contexts. A Script context comprises

• common variables (context variables), which are created with var and are visible from all scripts running in this scriptcontext, as well as local functions (defined with local function). These variables and functions are not visible from other scriptcontexts. Only global variables created with glob are both visible and modifiable from all contexts.
• One or more scripts that can run in this context, possibly even at the same time. A script running in a script context creates at least one so-called thread (meaning: "execution thread"), and can also start further threads with the concurrent construct.
• the option of terminating all threads running in this context. For example, when a scene is called, all running scripts/threads in the script context of the affected output (device) are terminated, e.g. scene scripts (see below). The abort() function also allows all scripts in the same scriptcontext to be terminated.
• possibly context-specific functions to interact directly with the context (e.g. of a device). In the devicecontext, for example, there are output, sensor(), input(), button() (and view for LEDchain devices) to access inputs and outputs of the respective device.

In addition to these different contexts, there is also the global context. This contains all global variables defined with glob from all other contexts, as well as all functions defined with function or global function.

The maincontext - the "main programme"

There is only one maincontext per application (P44-DSB or P44-LC device).

The following scripts run in the mainscontext:

The mainscript

The mainscript is started when the P44-xx device is started/restarted (or after restartapp()) and then runs in parallel with the other functions of the device. It can therefore be used to execute a few actions only briefly at startup, but can also contain a permanently running "main programme". On P44 devices, it can be found in the web interface under p44script.html - i.e. if the normal web interface is http://192.168.42.73, for example, the main script can be called up under http://192.168.42.73/p44script.html.

The REPL

The REPL (Read-Execute-Print-Loop) is used to enter and try out p44script commands line by line.

On P44 devices, it can be found in the web interface under repl.html - For more information see here.

The Evaluatorcontext - Evaluators

Evaluators are user-defined devices that monitor and analyse ("evaluate") one or more sensor or digital inputs and calculate a result, which in the case of P44-DSB is forwarded to the Digital Strom server (dSS). This enables sensor evaluations that may be difficult or impossible to implement with the "User-defined states" app in the dSS. Derived sensor values can also be created with an evaluator - e.g. the total power of a 3-phase current measurement or the average of several temperature sensors.

The following scripts/evaluations run in the Evaluatorcontext:

The Conditions

These are the expressions that trigger an evaluator.

For evaluators with yes/no output signal or action evaluators, there is one condition for switching on and one for switching off. Both are evaluated in the Evaluatorcontext. However, they are not complete scripts, but only expressions whose result is evaluated as true (!=0) or false (==0). They cannot contain functions that may take a long time to execute, such as delay() or httprequest().

For sensor evaluators whose output is a sensor value, there is only one expression whose result is used as the output value of the sensor. is used.

The Action

With action evaluators, it is not a signal or sensor value that is influenced, but the action script is executed. This also runs in the evaluator context, like the trigger conditions. It is therefore possible to refer to a variable in a trigger condition that is changed in the Actionscript (for this to work, the trigger conditions are always evaluated again after the Actionscript has been executed so that "feedback" is actually recognised).

The devicecontext - scripting in individual devices

Each device visible in the device list in a P44-DSB or P44-LC (=device) has its own devicecontext. Scripts run here that essentially concern this one device and its inputs and outputs, and therefore also have direct access to these (see output, sensor(), input() script functions).

The following scripts run in the device context:

The Scene scripts

Scene scripts are assigned to a specific scene in a specific device with output and are always executed when the corresponding scene is called. Scene scripts enable transitional and permanent effects (e.g. a slow continuous colour change).

A scene script runs in devicecontext, but only one at a time. If a scene script is still running while another scene is being called, it is cancelled - and, if available, the scene script of the newly called scene is started. Scene scripts can be started in the Special scene settings via the P44-DSB or P44-LC web interface.

The implementation context of a scripted device

The following scripts run in the implementation context:

The implementation script

Each scripted device has its own implementation script, which can be accessed via the pencil button or the "Edit Implementation script..." button in the device's info dialogue.

The Scriptcontext of a trigger (only for P44-LC-xx)

In the standalone controller P44-LC, i.e. the version of the product that functions independently without a Digital Strom connection, there are Triggers in addition to the Devices. These contain a trigger condition and an action script that is executed (triggered) when the condition is met. The trigger condition and the action script both run in a separate, private context of the trigger, the trigger context.

Script language

The syntax of p44script is strongly orientated towards JavaScript (and this towards C/C++). However, as far as the available standard functions and language constructs are concerned, p44script is deliberately not the same as JavaScript. p44script is designed to make programming tasks for lighting and other installations as simple as possible, and has specific features for this purpose that are not available in JavaScript:

• an easy way to execute pieces of code in parallel to other processes using the concurrent construct
• the ability to react to events such as sensor value changes, button presses, input changes, time sequences but also the arrival of network packets, web accesses etc. with the on (...) { ... } construct.
• Among the standard functions there are several such as maprange(), cyclic() or random(), which can deal with frequently occurring problems in automation tasks conveniently, solidly and with all the necessary options - which is of course also possible in standard languages, but with far more effort.
• Standard functions for controlling HTTP APIs (httprequest(), websocket(), geturl(), puturl()) locally in the network or in the cloud, and to find devices in the local network via DNS-SD (dnssdbrowse()).
• There are also deliberately omitted things, e.g. bitwise And/Or/Xor. Although these are important for bit manipulations, they are difficult to understand for non-computer scientists - in p44script there are therefore more convenient functions bit(), setbit() and flipbit().
• For simple handling of clock times, as they often occur for switching tasks, time values can be written directly as such, e.g. 12:30 (half past twelve) or 25.May or 25.5. for calendar dates.
• For light controls, the position of the sun is often important; p44script can use sunrise(), sunset(), dawn() and dusk() to calculate the corresponding times for each day of the year (depending on the geo-coordinates set for the device).
• "Annotated" null values help to understand why an operation or function does not return what you might expect, in that the null value is not simply "null", but carries an explanatory text (the annotation) which is displayed when debugging in the IDE or in the log.
• Easy access to the components of the system:
  • devices: lights, sensors, buttons etc. managed by the system via device()
  • Scenes: combinations of output values set by the user on one or more devices via scene().
  • Triggers: (P44-LC only) user-configured conditions with actions, e.g. timers, reaction to sensors etc., with trigger().
  • Views: (setups with LED chains/matrices) visual construction of complex light objects with the p44lrgraphics subsystem, via view or lgr (rootview).
  • I/O: Inputs and outputs of all types of hardware via digitalio(), analogio().
  • Subsystems: Subsystems such as SPI, I2C, modbus, DC motor control, p44lrgraphics for LED graphics or the features (see below)
  • Features: Subsystems from plan44 projects with specialised functionality (such as RFID readers for pseudonymous visitor identity in exhibitions, or control of split-flap displays), which may still be useful. Details see p44features on Github.

This list is intended to provide an overview of what is available in p44script. A detailed description of all constructs, operators, functions and system objects can be found in the Quick Reference), which is also built into every P44-xx setup (button Docs... in the system tab and in the IDE, or corresponding links at the bottom of the script text fields).