Panel Commands


Panel commands are actions the micro-controller can command to the APP and, thus, that will be executed on the user's mobile device (in contrary of normal serial commands that are executed on the WiFi modules). Panel commands are conceived to request actions for changing some aspects of the graphical panel currently displayed on the screen (e.g. for dynamically changing the appearance of some objects or containers) but also for interacting with the internal resources of the mobile device and its operating system.

Panel commands are objects (virtual objects since they do not have a graphical appearance) so they follow the general syntax of common objects. In particular, they are sent and synchronised exactly as other normal objects (such as LEDs, Switches and so on). A total of 16 command slots exist (ID ranges from 0 to 9 and from A to F), each of them can contain a command string. When the micro-controller inserts a command string into a command slot, the µPanel system will send it to the APP as soon as possible. If the APP is not running the command is kept into its slot and delivered later (as soon as the mobile APP is on and connected). Exactly like other objects (e.g. LEDS), if the micro-controller inserts a new command string into an already filled command slot, the old command string is replaced by the new one. Therefore, the following 2 general rules apply:

  1. if the micro-controller changes the command string contained into a command slot before the old command is actually sent to the APP, the old command is lost and it will be never sent to the APP (this is exactly what happens for other objects: if you both turn on and off a LED when the APP is not connected, as soon as the APP connects only the last LED status (OFF) will be sent)
  2. the commands contained in all the command slots are received and executed by the APP each time the panel is received, unless a special option (SEQ) is set during the command string definition in order to tell the APP to execute each command only once. 

Like other normal objects, panel commands can be set during the panel definition and can be changed later during the panel use. However, it is NOT mandatory to create a command slot during the panel definition to enable its subsequent use during run time (i.e. where # prefix is required, as explained below). Obviously, if a command slot is created and filled with a command string directly during the panel definition, the command is executed by the APP as soon as the panel is received and displayed.

An optional argument, called SEQ, permits to attach a SEQuential number to any issued commands. When the SEQ number is attached to a command, the APP will execute the command only once, even if it is received multiple times. In fact, the APP maintains in its memory its own SEQ counter and the received command will be executed only if its SEQ number is greater than those of all the previously received commands. The APP SEQ counter is cleared ONLY when a command with SEQ = 0 is sent. Please note that, the APP has only one global SEQ counter and it is therefore shared by all the command slots. Please note also that commands without SEQ argument or with SEQ = 0 are always executed.

When the command SEQ argument is specified, the micro-controller can request the APP to acknowledge the command execution simply by appending the upper case character A to the SEQ number. In this case, when the APP executes the command an acknowledge message is sent to the micro-controller, reporting the command slot ID and the SEQ number of the executed command.


1. Object definition (not mandatory)


Panel commands can be included in the panel definition using the following syntax:

C ID


[:SEQ[A]]
: command ;;

 

Where the brackets [ ] denote optional fields. Please note the double semicolon at the end of the command definition. This is necessary since commands (or their parameters) could contain themselves a semicolon symbol.

The following table describes the meaning of each field.

 

Field Lenght Description Value
C
1 char
Field that defines the virtual object panel command C
ID 1 char Unique ID that identifies the command slot to be used. 
This field can be a decimal digit or an upper-case character in the range 0..9 or A..F.
The max number of panel command slots available is 16.
The maximum length of the command string (including the optional SEQ field) that can be inserted into command slots is of 60 characters, with the exception of the panel command slots with ID = {0,1,2} (on firmware 003 or later) that are bigger and that can contain up to 1000 characters. Please note that such bigger slots consume a system buffer of 1024 bytes, so if not necessary, it's recommended using first ID in the range (3,9)-(A,F). Please refer to the Buffer section to find more information about the use of system buffers.
(0,9)-(A,F)
SEQ 
variable It's any decimal number representing an optional argument that can be used to attach a sequential number to the command. If this argument is specified, the APP will actually execute the issued command only if its SEQ number is bigger than those of all other previously issued commands. If SEQ is 0 (zero) the APP will clear its SEQ counter, re-enabling the execution of commands from SEQ = 0. Please note that the SEQ counter is a global value shared among all the command slots and that the SEQ counter is NOT cleared upon panel definition (the APP SEQ counter is cleared ONLY when a command with this field set to zero is sent)
decimal number
A
1 char Optional character that can be specified only when the SEQ field is specified as well. This character can be only the upper case character A. When specified, the APP will send a message to the micro-controller to acknowledge the command execution. E.g. when the command C3:5A:.... is issued, the following message will be sent to the micro-controller upon command execution: #C3:A5
where C3 represents the command slot with ID=3 and A5 represents the Acknowledge message of the command with SEQ=5 
A
command
variable Defines the specific command with its expected parameters. See below for the command list. The max command length is: 60 characters for panel command with ID in the range (3,9)-(A,F) and 1024 for panel command having ID in the range (0,2) and for firmware 003 or later.
ascii

 

 

2. Object usage


 Send a panel command (Panel <--- WiFi Module <-- Controller)

The syntax to use a command slot during the run time is :

Syntax

#
C
ID [:SEQ[A]] 
: command

where the meaning of each field is the same as described above in "Command definition"

Note:

As stated above, the panel commands follow the same panel synchronisation rules of other objects: if the user's micro-controller sends a sequence of serial commands into the same command slot, when the APP is offline, only the last command will be sent to the APP when the connection is established. So, if the micro-controller defines a panel command with ID=0 and sequentially sends: #C0:command_1 and then #C0:command_2, when the APP will be restarted, the panel will execute the command_2 only.

 

3. LIST of existing Commands



Command 's'  (dynamically change stylers of objects and containers)

This command permits to change the stylers of objects and containers without sending a new panel. This command is useful to animate the panel during the run time, for instance for dynamically changing position, size, colours of objects or container. To use this command a unique global ID must be assigned during the panel definition to the object/container to animate. Global ID can be assigned by means of the styler ~ (tilde, ascii code 126) . Please refer to this styler section for more details on this styler usage.

Please note that all styler changes applied to objects/containers are always performed with respect to their initial state specified in the panel definition (previously changes applied through previous commands do not affect the final appearance).

Command 's' syntax

The field command of the panel command object in this case is:

s
~
global_id
: new_stylers 

 

where:

  • the lowercase character 's' identifies this command
  • the character '~' is the styler that is used to attach a global ID to the object/container to animate
  • global_id is the decimal value that has been assigned to the object/container through the styler during the panel definition. Please note that the global_id is not the object ID.
  • new_stylers represents one or more stylers that will overwrite the stylers defined for that object/constructor during the panel definition. Please note that only the specified stylers will be changed and that all the other stylers will remain unchanged with respect to their values specified in the panel definition. If the new_stylers field is empty, the object/container will return to its initial appearance specified in the panel definition.
 

Example 1.

Panel definition:

Define a panel with a container (having global_id = 1 with following styles: background = white, dimension= 50x50, and styler "align content at center") and a object led inside (having object ID = 1 and status off).

{~1!FFF%50,50^L1G:0;}

Object usage:

Using the panel command (slot 3), change the style "background color" (to color red) and the dimensions (to 20x20), add the style "border", of the container with global id = 1, leaving the other styles as specified in the panel definition:

#C3:s~1:!F00-%20,20

Note: the command can be specified directly into the panel definition as follow:

{~1!FFF%50,50^L1G:0;}C3:s~1:!F00-%20,20;;

 

Example 2.

Panel definition:

Define a panel with a message (having object  ID = 0, global ID = 12, style color of the text = white, style size = 20, message "Alarm OFF") and a button (having object ID = 1, and text = "set alarm"):

M0~12#FFF*20:Alarm OFF;/10B1:set alarm;

Object usage

Using the panel command (slot 3), change the style color of the text '#' (to red) and size '*' of the object  with global ID 12:

#C3:s~12:#005*30


Example 3.

Panel definition:

Define a panel with: object DESKTOP with a background image and a container (with global ID = 1) in which is placed an ANALOG INDICATOR object, three BUTTON objects and 3 LED objects.

Object usage:

Dynamically change at each second the background color of the container (red, green, blue, transparent)

 See the code of this example

 

 


 

 


 
Panel layout

dynamic changes

dynamic changes

dynamic changes

  

 

Example 4 - Animation: Bouncing Ball

Panel definition:

Define a panel with: object DESKTOP with the background image n. 21 and a container (with a background image n. 2) in which is placed a PICTURE object (smile emoticon n. 7.55) having the global ID = 1.

Object usage:

Dynamically change the absolute position of the object PICTURE (by changing the style '@')

 See the code of this example

Video of the Animation: