LLExec Web Server

Summary

This article describes the API that LLExec integrated Web Server offers to access plc variables and parameters.

Variables access

To access variables (also called symbols), the web server offes two http methods: GET to read simple variables and PUT to write simple variables.
The symbols that can be accessed are global variables of simple types (numeric, boolean, string).
That symbols can also be structured query of the type my_arr[123].my_field, with the constraint that the value of the expression must be simple typed.

GET symbols method syntax

The syntax of the url to do the GET method:

http://1.2.3.4/api/sym?sym_name1&sym_name2&sym_name3

The content value of any symbol will be written on a single line.

PUT symbols method syntax

The syntax of the url to do the PUT method:

http://1.2.3.4/api/sym?sym_name1=value1&sym_name2=value2&sym_name3=value3

Where the valueN is the value of the variable N. String values doesn't need limiters, and spaces must be coded in the URL with the string %20 . For example:

PUT http://1.2.3.4/api/sym?var_bool=true&var_int=123&var_string=hello%20world

Parameters access

To access parameters web server offes two http methods: GET to read parameters and PUT to write parameters.
To access parameters their index must be known, eventually with subindex (this indexes are called IPA): IPA examples are 10000.12' or 60000 .

GET symbols method syntax

The syntax of the url to do the GET method:

http://1.2.3.4/api/par?ipa1&ipa2&ipa3

The content value of any parameter will be written on a single line.

PUT symbols method syntax

The syntax of the url to do the PUT method:

http://1.2.3.4/api/par?ipa1=value1&ipa2=value2&ipa3=value3

Where the valueN is the value of the variable N. String values doesn't need limiters, and spaces must be coded in the URL with the string %20 . For example:

PUT http://1.2.3.4/api/par?10000=true&10010=123&10021=Hello%20world

Browsing variables

The Web Server offers a method to obtain information about variables on the system.
The url for browsing symbols have to be colled with http GET method and is as follows:

http://1.2.3.4/api/symlist?name=pattern

The pattern can be a variable name, the jolly * character, or a name with the jolly character prefixed or suffixed.
Examples are

http://1.2.3.4/api/symlist?name=*
http://1.2.3.4/api/symlist?name=my_variable_name
http://1.2.3.4/api/symlist?name=count*
http://1.2.3.4/api/symlist?name=*substr*

The output of the query is a JSON containing the list of the symbols that matches the pattern, with attributes like name, type and description.
For example, if in my system i do the query

http://127.0.0.1/api/symlist?name=*

I obtain the following output:

[
   { name:"$$STKLIMIT$$", type:"DWORD", descr:""},
   { name:"$$STKPOINTER$$", type:"DWORD", descr:""},
   { name:"$$DEBUGID$$", type:"DWORD", descr:""},
   { name:"CNT", type:"INT", descr:""},
   { name:"STR", type:"STRING", descr:""},
   { name:"SYSPLCSTATUS", type:"PLC_STATUS", descr:"Internal PLC Status"},
   { name:"SYSTIMER", type:"UDINT", descr:"System timer [ms]"},
   { name:"SYSPLUGINSDATARO", type:"BYTE", descr:"RO allocation area for plugins"},
   { name:"SYSPLUGINSDATARW", type:"BYTE", descr:"RW allocation area for plugins"},
   { name:"SYSUSERDATABLOCK", type:"BYTE", descr:"Data block available for user data mapping"},
   { name:"SYSUSERDATABLOCKRETAIN", type:"BYTE", descr:"Data block available for user data mapping - Retain DB"},
   { name:"SYSHOURS", type:"USINT", descr:"Values 0-23"},
   { name:"SYSMINUTES", type:"USINT", descr:"Values 0-59"},
   { name:"SYSSECONDS", type:"USINT", descr:"Values 0-59"},
   { name:"SYSDAY", type:"USINT", descr:"Values 1-31"},
   { name:"SYSDAYOFWEEK", type:"USINT", descr:"Values 0-6 where 0 is Sunday "},
   { name:"SYSMONTH", type:"USINT", descr:"Values 1-12"},
   { name:"SYSYEAR", type:"UINT", descr:"Values 4 digit"},
   { name:"SYSCOPMSDOFAILEVENT", type:"COPMSDOFAIL", descr:"This struct is filled just before an occurred parametrization SDO fail is signaled to PLC task"},
   { name:"SYSCOPMNODESTATUSCHANGEDEVENT", type:"COPMNODESTATUSCHANGED", descr:"This struct is filled just before a node status change is signaled to PLC task"},
   { name:"SYSCOPMEMERGENCYEVENT", type:"COPMEMERGENCY", descr:"This struct is filled just before an occurred emergency event is signaled to PLC task"},
   { name:"SYSCOPMPDOERREVENT", type:"COPMPDOERR", descr:"This struct is filled just before a malformed PDO RX event is signaled to PLC task"},
   { name:"SYSCOPMEVENTID", type:"DINT", descr:"This value is set with the event ID value. The struct corresponding to the ID set can be used in the notify event task when it is executed"},
   { name:"SYSCOPMRESYNCINFO", type:"COPMRESYNC", descr:"This struct is filled just before a master/slave resync event"},
   { name:"SYSCOPMMASTERSTATUS", type:"COPMMASTERSTATUS", descr:"System CANOpen Master Diagno. It is a structure of type COPMMASTERSTATUS composed ..."},
   { name:"SYSCOPMNODESTATUS", type:"COPMNODESTATUS", descr:"System CANOpen Master communication status. It is a structure of type COPMNODESTATUS composed ..."},
   { name:"SYSCOPMSDOSCHEDULINGDIAGNO", type:"COPMSDOSCHEDULINGDIAGNO_SLAVE", descr:"This structure show for each node the last SDO scheduled succeded and failed"},
   { name:"SYSMBMRTUNODESTATUS", type:"MBMNODESTATUS", descr:"System Modbus Master RTU communication status for network with id MB_RTU_NETWORK_0. ..."},
   { name:"SYSMBMRTUNODESTATUS_1", type:"MBMNODESTATUS", descr:"System Modbus Master RTU communication status for network with id MB_RTU_NETWORK_1. ..."},
   { name:"SYSMBMRTUNODESTATUS_2", type:"MBMNODESTATUS", descr:"System Modbus Master RTU communication status for network with id MB_RTU_NETWORK_2. ..."},
   { name:"SYSMBMRTUNODESTATUS_3", type:"MBMNODESTATUS", descr:"System Modbus Master RTU communication status for network with id MB_RTU_NETWORK_3. ..."},
   { name:"SYSMBMTCPNODESTATUS", type:"MBMTCPNODESTATUS", descr:"System Modbus Master TCP communication status. It is a structure of type MBMTCPNODESTATUS composed ..."},
   { name:"SYSALARMCFGOK", type:"BOOL", descr:"Alarm manager properly configured"},
   { name:"SYSALARMACTIVE", type:"BOOL", descr:"At least one alarm is active (associated condition holds true)"},
   { name:"SYSALARMWAITACK", type:"BOOL", descr:"No alarm is active but at least one alarm is waiting for acknowledgement"},
   { name:"SYSALARMCOUNT", type:"UINT", descr:"Number of active alarms"},
   { name:"$$CODEBASE$$", type:"UDINT", descr:""},
   { name:"$$CODESTART$$", type:"UDINT", descr:""},
   { name:"$$CODESIZE$$", type:"UDINT", descr:""},
   { name:"$$CODEEND$$", type:"UDINT", descr:""},
   { name:"$$DATASIZE$$", type:"UDINT", descr:""},
   { name:"$$AUXDATASIZE$$", type:"UDINT", descr:""},
   { name:"$$BITDATASIZE$$", type:"UDINT", descr:""},
   { name:"$$RITDATASIZE$$", type:"UDINT", descr:""}
]

Browsing parameters and menus

LogicLab allows to define application parameters and status variables, with an IPA a type and some others attributes.
From the perspective of the web server parameters and status variables are the same type of objects, so we simply refer as parameters.
In LogicLab you can also define menus in wich some parameters can be added: every menu is identified by an unique id.
Menu can be nested.
An user can define also custom web pages, that can be nested also in mixed mode with menus, they have theirs own unique id.
The web server offer two API to browse menus, custom pages and parameters, both can be called with the GET http method. The two urls are:

http://1.2.3.4/api/parlist?id=unique_id_of_a_menu
http://1.2.3.4/api/menulist?id=unique_id_of_a_menu&recursive=[TRUE | FALSE]

Parlist API

With this API an user can query the list of parameters contained in a menu, specified with its id
If the id is set to 0, all the application parameters are listed.
The output is a JSON containing the list of parameters with teirs attributes.
For example if I query the url

http://127.0.0.1/api/parlist?id=0

to my server I obtain the following output:

[
  { ipa: 10000, name: "Par1", typepar: "short", readonly: true, defval: 0, descr: "", form: "", um: ""},
  { ipa: 10001, name: "Par2", typepar: "boolean", readonly: true, defval: 0, descr: "", form: "", um: ""}
]

The attributes that can be found for every parametes are:

• ipa: the IPA of the parameter
• subindex: if presemt, the subindex of the parameter. Note that the subindex presence depends on how LogicLab manage the address of parameters.
• name: the name of the parameter.
• typepar: the type of the parameter.
• readonly: the attribute read-only of the parameter.
• defval: the parameter's default value.
• descr: the description of the parameter.
• form: the printf-style desired format.
• um: the measure unit for the parameter value.

Menulist API

With this API an user can query the menus and custom pages structure,
the id specifies the starting node, if zero it shows all the root menus.
If the recursive parameters is TRUE nested menus and custom pages are shown.
For example if on my system I query the url

http://127.0.0.1/api/menulist?id=0&recursive=TRUE

i obtain the foolowing JSON output:

[
  { type: 0, id: 30000, caption: "MyMenu", children: 
    [
      { type: 0, id: 30001, caption: "Nested Menu" },
      { type: 1, id: 30002, caption: "Nested Custom Page", link: "custom.html", icon: "custom.ico" }
    ]
  }
]

the attributes are:

• type: 0 is a menu, 1 is a custom page
• id: the menu or custom page unique id
• caption: the menu or custom page title
• link: only for custom pages, its URL
• icon: only for custom pages, its icon
• children: when recursive=TRUE, this is a list of nested elements