====== Web API ====== The Web API can be used to run scripts against the ComfileHMI panel PC from a modern web browser, or other web client. With some web programming skill, it can be used to create real-time web interfaces that can read, write, or otherwise control the ComfileHMI panel PC from any modern web browser or other web client. It is only compatible with CHC model panel PCs running firmware version 3.15 or later. ===== Query Format ===== A query against the web API can take the following format: http://{panel_pc_ip_address}:{port}/{command}/{password}/{expression} * ''{panel_pc_ip_address}'' : The IP address of the ComfileHMI panel PC you wish to query * ''{port}'' : The remote control port of the ComfileHMI panel PC. * ''{command}'' : Either ''script'', ''open'', or ''download''. See more information below. * ''{password}'' : The ComfileHMI panel PC's remote control password. If no password is configured in the //Runtime Settings-->Server-->Password Settings//, then it can be omitted as http://{panel_pc_ip_address}:{port}/{command}//{expression} * ''{expression}'' : A ComfileHMI expression for the ''{command}'' See more information below. Please note that if entering this command in a web browser's address bar, it may require URL-encoding certain characters: * ''#'' → Substitute with ''%23'' * ''%'' → Substitute with ''%25'' * ''\'' → Substitute with ''%5C'' (If it is a file path, you can also simply substitute ''/'') Examples: * http://192.168.0.20:9138/script//$a="3 is 60%25 of 5";vars_to_json("$a") * http://192.168.0.20:9138/open//storage card/web_hmi.html * http://192.168.0.20:9138/download//storage card/sub/data.bin * http://192.168.0.20:9138/script//filenames_to_json("storage card/dir") ==== Command ==== The command determines what action to perform. There are currently three. === `script` === This command utilizes the same scripting engine as that of [Action > Script] in Comfile Studio. The ''{expression}'' can be one or more expressions separate by semicolons ('';''). Use ''vars_to_json'' and/or ''mem_to_json'' to return the values of variables or internal memory as JSON to the browser. See Example: * http://192.168.0.30:9138/script//a=a+1;vars_to_json("a") === `open` === This command will open a file in a web browser. Formats recognized by most modern web browsers are HTML, image files, audio, and video files. When using the ''open'' command, the browser will attempt to display the file directly in the browser. The ''{expression}'' is simply a path to a file. If the query fails, a JSON response will be returned. Example: * http://192.168.0.30:9138/open//storage card/MyWebHmi/index.htm === `download` === This command will download the file through a web browser. Contrary to the ''open'' command, this command will attempt to download the file instead of displaying it in the browser. The ''{expression}'' is simply a path to a file. If the query fails, a JSON response will be returned. Example: * http://192.168.0.30:9138/download//storage card/logs.txt ===== Querying a ComfileHMI Panel PC from Another ComfileHMI Panel PC ===== A ComfileHMI panel PC can act as a client of another ComfileHMI panel PC using the HTTP Request action. {{ :comfilehmi:web_api:comfilehmiwebclient.png }} When a variable or internal memory value is received it is copied to a variable of the same name or to an internal memory location at the same address as that of the server. Additional actions can be specified to be executed after the JSON response has be processed. If a query fails, the functions ''last_json_error_code()'' and ''last_json_error_message()'' can be used to obtain additional information and take appropriate action. See the [[comfilehmi:hmieditor_function:index#web_api_functions|Web API functions]] for more information. ===== Querying a ComfileHMI Panel PC with a Modern Web Browser ===== Using modern web programming techniques (HTML, CSS, and JavaScript) it is also possible to create real-time web interfaces to a ComfileHMI that is running a project locally. The following examples illustrate that technique. To run the examples, download the HTML file, update the IP address in the source code, copy it to the "Storage Card" folder of the ComfileHMI panel PC, and then open the file in a web browser by navigating to the URL... http://{panel_pc_ip_address}:{port}/open/{password}/storage%20card/{filename}.htm It is possible to run the examples directly from a PC, but due to [[https://en.wikipedia.org/wiki/Cross-origin_resource_sharing|CORS restrictions]] the browsers's security features will need to be disabled before loading the file. For the Chrome browser that can be done by starting the browser with the following command: C:\Program Files (x86)\Google\Chrome\Application\chrome.exe" --disable-site-isolation-trials --disable-web-security --user-data-dir="C:\temp" ==== Example 1 ==== Assume a ComfileHMI panel PC is running a project with a variable named ''a'' and data at internal memory locations 5 and 6. The following HTML page can be used to read those values in real-time and display them a web browser. {{ :comfilehmi:web_api:webapiexample1.png }} {{ :comfilehmi:web_api:sample1.htm | Download this example HTML file }} (Right-click and choose the menu option to save to your PC) ==== Example 2 ==== The following example will write the slider's value to a variable ''a'' on the ComfileHMI panel PC. It will then read, in real-time, the value of ''a'' and display it on the gauge. {{ :comfilehmi:web_api:sample2.png }} {{ :comfilehmi:web_api:sample2b.png }} {{ :comfilehmi:web_api:sample2.htm | Download this example HTML file }} (Right-click and choose the menu option to save to your PC) ==== Example 3 ==== The following example illustrates how to display a list of log files in the browser, giving the operator the ability to download and/or delete the files from the ComfileHMI panel PC. {{ :comfilehmi:web_api:sample3.png }} {{ :comfilehmi:web_api:sample3.htm | Download this example HTML file }} (Right-click and choose the menu option to save to your PC) ===== JSON Response Format ===== ^ Field Name ^ Type ^ Description ^ | success | boolean | Whether or not the query succeeded. ''true'' if success. ''false'' if error. | | vars.{HMI variable names} | number | The value of the variables requested with the function ''vars_to_json()'' | | vars.{HMI string variable names} | string | The value of the string variables requested with the function ''vars_to_json()''. String variable names start with ''$''. | | mem.{HMI internal memory start address} | array | Array of internal memory values requested with the function ''mem_to_json()'' | | error.code | number | The error code if the query failed. | | error.message | string | The error message if the query failed. | | filenames | array | List of file names requested with the function ''filenames_to_json()''. | | dirnames | array | The list of subdirectories requested with the function ''dirrnames_to_json()''. | Example 1: An example of a successful response. { "success": true, "vars": { "temperature" : 16.7, "$city" : "Seoul" }, "mem" : { "20" : [31,43,21] } } Example 2: An example of the response returned if an error occurs while processing the query. { "success" : false, "error" : { "code" : 4011, "message" : "Command syntax error." } } === Error Codes and Error Messages === ^ Error Code ^ Error Message ^ | 8047 | The format of the JSON received was incorrect. | | 4011 | The format of the query was incorrect. | | 4010 | An unknown command. | | 3010 | The panel PC does not support the Web API: The Web API is only supported by the CHC series panel PCs. | | 3009 | An attempt was made to connect to the panel PC without a project running. | | 3012 | The remote control password was incorrect. | | 3013 | Script syntax error. | [[comfilehmi:#Shapes_and_Graphics:|Back to ComfileHMI]]