p44script IDE - Integrated development environment

What the IDE offers

The IDE provides access to all functions and tools that are useful and convenient for creating scripts:

• A text editor that knows the syntax, function names and language constructs of p44script and can colour them accordingly and also auto-complete them while typing. Thanks to tabs, several scripts can be open at the same time and their contexts can be called for inspection (see below).
• A console in which p44script commands and expressions can be executed interactively in the context of the script displayed, so that variables, for example, can be inspected and changed if necessary.
• A log window in which the log file is continuously displayed, as well as options for setting the log level (level of detail)
• A debugger, i.e. the possibility to set breakpoints in scripts at which the execution pauses, and then on the one hand to view variable values via the console, to change them if necessary, and on the other hand to continue the execution in individual steps in order to see exactly what is happening.

None of this is special compared to other programming environments and IDEs - except for the fact that the entire IDE is integrated into the P44 device, has no dependencies on the Internet or any clouds and is therefore also suitable for installations that should run and remain maintainable for decades.

You need nothing but a web browser to write and maintain a p44script application!

Overview

Working in the IDE

Open scripts

The popup at the top left is used to open scripts for editing in a tab (or, if already open, to activate the corresponding tab). It contains:

• the mainscript. This is the script that is started when the device (or the vdcd application on it, see also restartapp() function) is started. It is often used to set up global things, e.g. the configuration of SmartLED chains/matrices or initialisation of other hardware.

• the p44script playground. This is a script that is not saved permanently, i.e. it is lost after a device restart (but does not cause flash wear). This "playground" is intended for quickly trying out larger scripts. With the Eval key, the script can also be evaluated as an expression and then shows the result value in the console (similar to commands entered directly in the console, but several input lines are possible)

• Implementation scripts of Scripted Devices (if available). These are the scripts that contain the functionality of self-defined devices, e.g. a virtual weather station or many other things.

• Actions from action evaluators (if available). These are scripts that are triggered in evaluator devices which have been created as action evaluators, when the corresponding condition is met (in contrast to the other evaluator types, whose status is simply forwarded to the higher-level SmartHome system, i.e. Digital Strom in the case of P44-DSB or matter).

• Actions of triggers (only P44-LC, only if available). Triggers are similar to action evaluators - these can be used, for example, to program timer functions, customised reactions to button presses or other inputs. In addition, triggers can also appear as a button on the Custom Action page with configurable text and colour so that they can be conveniently triggered by users.

• Scene scripts (if available). All devices with an output (lights, relays, shutter motors, etc.) have scenes that can save and recall the states of the output. Optionally, a scene script can be invoked when a scene is called, which, for example, may implement a dynamically changing coloured light scene.

Create scene scripts

Each device with an output could theoretically have 90 scene scripts (there are that many possible scenes), but in practice, of course, only very few of them are actually used. Therefore, the popup does not display a myriad of empty scene scripts for selection, but only those that are in use.

This means that if a scene does not yet have a script, it cannot (yet) be opened in the IDE. It must first be activated in the Scene settings of the web interface - from there it can then be opened directly via the link at the bottom right of the script input field, even if the text field is still empty. From then on, the script is available in the open popup of the IDE. Alternatively, a script text can already be entered in the scene settings (a comment line is sufficient) and the dialogue can be closed normally. Now the scene script is no longer empty and is available in the IDE in the open popup.

Console/REPL

The black panel at the bottom left is the console, which functions as a REPL (Read-Execute-Print Loop), i.e. p44script instructions can be entered there directly and executed by pressing Return/Enter - the result is displayed immediately below.

• The last line highlighted in green shows the current context in which the input is executed. This is the context of the script open in the editor, or, if the light green area appears at the bottom and indicates a paused thread and a green line marks the pause position in the script editor, it is the context of this thread. All input is executed in this context. This makes it possible to access the specific variables, objects and functions of the respective context. For more on script contexts, see here.

• If you type something below the line highlighted in green and then press Enter, what you have typed is executed and the result is displayed.

• If a text passage is selected somewhere in the console and then Enter is pressed, the selected text is copied to the end (i.e. below the line highlighted in green) and then executed immediately. This is useful for reusing something that has already been typed.

• If Enter/Return is pressed on a line above the line highlighted in green without text being selected, the entire line is copied to the end and executed.

• The entire console text can be edited, i.e. changes can be typed before a line is executed again with Return/Enter. Opt-Return/Enter can be used to enter a line break without executing the line.

• The console content can be deleted with the corresponding button or with Cmd/Ctrl-K. The input area (below the context line highlighted in green), the currently selected text or the line on which the cursor is positioned is retained. Of course, you can also select sub-areas and delete them with the delete key. Undo (Cmd/Ctrl-Z) can be used to remove the result after executing a command and return to the input line.

• Results that are objects or arrays are displayed in JSON notation and can be expanded and collapsed using the small grey triangles in the left margin next to the line number to create an overview.

The log panel

The white panel at the bottom right continuously displays the log. The buttons below it can be used to pause and restart the output (but not the log itself!), delete the panel content and adjust the log level using the small pop-up menu. This is useful for keeping an eye on what is happening on the system, either in general or due to script actions.

Edit scripts

Scripts opened in an editor tab can be edited directly.

• There is a button at the bottom for saving, or Cmd/Ctrl-S. If a currently running script is saved, its execution is cancelled and a corresponding message appears in the log.

• To check the syntax, there is a button with a checkmark; this saves the script and if a syntax error is found, it is highlighted in red in the editor. Not all errors can be found in this way, many errors only occur at runtime and are only displayed after the script has been started.

• To start a script for debugging ( in single-step mode from the beginning), use the button with the spray can (this does not work with scene scripts, a breakpoint must be set on the first line, see below).

• The button with the green arrow is used to (re)start a script in its context. "Start in context" here means that the script is not only simply started, but also the things that normally happen around it in preparation (in particular: previous call of the scene for scene scripts).

• The Eval key =? is used to execute a script and display its result in the console. This makes no sense with most scripts integrated in devices or scenes! The button is mainly there to try things out in the p44script playground (see above).

Debugging

If a script does not work as intended, step-by-step execution and the ability to see what the current values in the variables are is very useful.

• A so-called breakpoint can be set with a click in the left margin of the editor.

  Script must have been started with the debugger open for breakpoints to be active

  Scripts that are already running when the IDE is opened do not trigger breakpoints. In this case, the respective script must first be restarted

• If the script execution reaches a breakpoint (comments are not executed, therefore breakpoints on comment lines have no effect), the execution is paused and the light green field with the debug buttons appears at the bottom.

• If several execution threads reach a breakpoint at the same time and are therefore paused, the popup menu that displays the thread (thread_68750) can be used to switch between the paused threads.

• The console always works in the context of the paused thread displayed. Inputs in the console are now executed in the same environment as if they were at the current execution position. This means that all variables of this current context, including local variables of a function currently being executed, or threadvars, are also accessible and can be displayed or assigned by typing the name. Also useful in the console are the introspection functions, which can be used to obtain information on available functions, fields etc.

• The script can be executed step by step using the singlestep buttons (Step, Step in, Step out) or the function keys F6, F7, F8. If there are several instructions on one line, the green bar remains on the same line, but the cursor shows the position within the line.

• Normal steps (Step, F6) execute function calls in one step, whereas with Step-In (F7) the step-by-step execution enters the function. Step-Out (F8) executes the rest of the function all at once; execution pauses only after the function call.

• With the Continue key, the thread continues to be executed normally until it is either finished, stopped or reaches a breakpoint again. The Stop button can be used to abort the thread - but this is not the same as aborting the whole script if the script has several threads running in parallel due to the use of concurrent or on (...) {...}!

  Paused code (e.g. on(...) handler) is not called repeatedly

  A breakpoint in code that may be called again and again from handlers or concurrent constructs, or for other reasons from the application, possibly in quick succession, could lead to a rapidly growing backlog of paused threads and thus to memory shortages. To prevent this from happening, code parts in which a paused thread is currently located are not executed again. Instead, a warning appears in the log.

• If the browser window with the IDE is closed or the network connection between the browser and device is interrupted, all paused threads are resumed after 20 seconds and the debugger is deactivated.

Further functions

• Documentation button at the bottom right: Calls up the built-in p44script quick reference, which always describes exactly the p44script version actually present in the device (while this online documentation describes the current version in each case, which may differ from the one present in a device to be serviced a few years from now).

• LED simulator: the coloured button at the bottom right opens a browser tab with a tool for simulating light installations using SmartLEDs (WS281x, SK6812) in the browser and inspecting and configuring the associated view hierarchy of the p44lrgraphics subsystem. This can be very useful for developing complex animations etc., or for remote maintenance to get an impression of what the LEDs are currently displaying, even if it is not possible to view them directly. The SmartLED subsystem is not active on all P44-xx devices; the LED simulator can also be called up there, but does not display anything. The LED simulator is most useful in parallel to the IDE in a separate window. For details, see LED simulator documentation.