WebHMI Docs

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Integration into other systems ======

WebHMI allows you to interact with other systems by running HTTP requests. For this, WebHMI has a library [[ https://github.com/Lua-cURL/Lua-cURLv3 | Lua-cURLv3]]. Using it you can easily send data to third-party systems and also request the necessary data from these systems.

This function is available since version 2.6.4520.

===== POST example =====

An example of a program executing an HTTPS request to send data as a file at URL https://example.com/upload:

<code lua>
function main (userId)
    
  INFO("Doing CURL");

  c = cURL.easy_init()
  c:setopt_url("https://example.com/upload")
  c:setopt_timeout(5)

  postdata = {
      name = {
          file="dummy.html",
          data="<html><bold>bold</bold></html>",
          type="text/html"
      } 
  }
  c:post(postdata)
  c:perform()
  c:close()

  INFO("CURL done");
end
</code>

Note that for SSL certificates correctly function, you need to have an exact local time. If there is a significant deviation of the local clock, https requests may not work. We recommend using time synchronization via NTP server.

===== GET example =====

Example of requesting a number in the GET request at URL http://demo.example.com/read-data?param=32 and writing it to the register with id=4356:

<code lua>
function main (userId)
  c = cURL.easy_init()
  c:setopt_timeout(5)
  c:setopt_url("http://demo.example.com/read-data?param=32")
  local res = "";
  c:perform({
        writefunction = function(str)
            res = res .. str;
        end})
  c:close()
  WriteReg(4356, res);
end
</code>

===== Implementing other requests like PUT =====

To implement other requests, you can use special field in the cURL for the custom methods.

Here is the example of PUT request to WebHMI itself from its Lua. 

<code lua>

function main (userId)
  local new_value = "new string"
  write_reg_with_API(1, new_value)
end

function write_reg_with_API(reg_id, val_)
    
  c = cURL.easy_init()
  
  c:setopt_url("http://127.0.1.1/api/register-values/" .. reg_id)    -- local host addr indicated
  c:setopt_timeout(2)
  
  c:setopt{[cURL.OPT_CUSTOMREQUEST] = "PUT"}
  c:setopt{[cURL.OPT_POSTFIELDS]    = '{"value":"' .. val_ .. '"}'}   -- insert value here
  
  c:setopt_httpheader({
      'Content-type: application/json',
      'Accept: application/json',
      'X-WH-APIKEY: 976FA578CF3B11ADA06564464B1F01823AF81C3D'         -- check APIKEY
  })
  
  c:perform({writefunction = function(res) str = res end })           -- you can print str for debug purposes 
  c:close()
end 

</code>
===== Example - connecting to a remote module via its web server =====

Most currently produced remote i/o modules have configuration and status web-page for diagnostic and setup. 
When you have a module which is not supported by the WebHMI and the usage of the custom protocol feature is complicated, there is another option of accessing the module through its embedded web-server with HTTP requests right from WebHMI. 

For a example we have the UC20-FBC-xxx (any bus Modubs, Ethernet/IP, DeviceNet etc) remote I/O module from Weidmuller. The module has web server for diagnostinc and setup:

{{ network:uremote_config_page.gif?direct&600 |}}

On this page you press **F12** to get necesssary information for the POST request:

{{ network:post_info_out.png?direct&600 |}}

Then, use this information for POST request in Lua script on the WebHMI:

{{ network:post_lua_example2.gif?direct&600 |}}

The function returns json object which you can then analize and check necessary fileds to read:

{{ network:json_viewer.png?direct&600 |}}

===== Notes on cURL usage =====

<WRAP center round important 80%>
In the fw of 4.0 version, the following issue was reported:
When there are multiple cURL requests from the WebHMI to the unavailable resource, a system crash may happen. The timeout settings won't affect the sysem behaviour. Use this feature with care when you need cyclical calls of multiple cURLs in your scripts:
  * use one script which detect availablity of the resource and locks following execution for a while
  * use external watchdog circuit to reset WebHMI if you use it to control mission - critical system. 

If the curl stability is the issue in your project, you can implement HTTP requests using custom protocol. See the [[http_get_custom |example]]
</WRAP>

==== HTTP / HTTPS requests ====
<WRAP center round info 80%>
Please note that HTTPS requests are only possible in **WebHMI Pro** version and virtualization images.
</WRAP>

==== Troubleshooting CURL requests from WebHMI ====

When troubleshooting your requests, you can turn on verbose information in your script. Please refer to the example below:

<code lua>
function main (userId)
    local res = ""    
    local c = cURL.easy_init()
    c : setopt{ url = 'http://danepubliczne.imgw.pl/api/data/hydro/id/153160210',
              timeout = 30, 
              httpheader = {'Accept: application/json',
                            'Content-Type: gzip, deflate, br',
                            -- 'Host: <calculated when request is sent>',
                        }
             }
     
     -- sw on verbose info 
     c : setopt{[cURL.OPT_VERBOSE] = 1}  
     c : setopt{[cURL.OPT_DEBUGFUNCTION] = function(...) 
                for i, v in pairs(arg) do DEBUG(i .. ' ' .. v) end 
                return 0
         end }  
     
     c : perform{writefunction = function(str)
                res = res .. str
            end}
        c : close()
     
        INFO(res)
        if (res == '') or (res == '%[%]')then 
            ERROR('No data in response!') 
        else 
            INFO('\n' .. res) 
        end
end
</code>