Getting started

An Edge App runs on a CoCoCo controller, close to the devices and services it connects. Use it to receive MQTT messages, monitor OPC UA values, poll SNMP or Modbus devices, respond to HTTP requests, or run permitted local commands. Lua handlers decide what to do when a message, reading or scheduled event arrives.

An Integration runs in the CoCoCo platform and coordinates tenant resources, Actions and workflows. Choose an Edge App when the work needs controller access to local equipment or protocols. An Integration can also include an Edge App definition for the controller-side part of a larger solution.

You write one reusable XML definition. It declares handlers, resources and the configuration the app needs. An installation selects that definition for a particular controller and supplies its addresses and credentials. Publishing a definition does not install or activate it.

For a first app, use one protocol and one handler. The MQTT example below listens for plant state messages and logs their topics. Before installing it, you need a controller that can reach the broker, a broker URL, credentials and its CA certificate. Keep those values in the installation, outside the XML.

<edge-app format="1" handle="plant-monitor" name="Plant monitor" log-level="info">
  <description>Receives state changes from the plant broker.</description>
  <config-schema>
    <schema type="object" xmlns="urn:cococo:json-schema:1">
      <additional-properties boolean="false"/>
      <property name="MQTT_CA" type="string" write-only="true"/>
      <property name="MQTT_PASSWORD" type="string" write-only="true"/>
      <property name="MQTT_URL" type="string"/>
      <property name="MQTT_USERNAME" type="string"/>
      <required name="MQTT_URL"/>
      <required name="MQTT_USERNAME"/>
      <required name="MQTT_PASSWORD"/>
      <required name="MQTT_CA"/>
    </schema>
  </config-schema>
  <handlers>
    <handler name="receive"><![CDATA[
bridge.log.info(params.topic)
return params.payload
    ]]></handler>
  </handlers>
  <mqtt-brokers>
    <broker name="plant" url="${config:MQTT_URL}" username="${config:MQTT_USERNAME}" keepalive-seconds="30" qos="1">
      <password config="MQTT_PASSWORD"/>
      <subscriptions>
        <subscription topic="plant/+/state" handler="receive"/>
      </subscriptions>
      <tls>
        <ca-cert config="MQTT_CA"/>
      </tls>
      <will topic="plant/edge/online" qos="1" retain="true">
        <payload>false</payload>
      </will>
    </broker>
  </mqtt-brokers>
</edge-app>

The root names the app. config-schema declares the four installation settings. The plant broker uses those settings, and its plant/+/state subscription calls the receive handler. The handler logs the incoming topic and returns the payload.

1. Import the XML, or open an Edge App draft in the source editor.
2. Choose Validate, correct any errors, then Save draft. Export XML keeps the current editor text, including unsaved changes.
3. Choose Publish when the saved definition is ready. Published versions are read only; use New version to make changes later.
4. Create an installation for the chosen controller, supply the declared settings, and activate it when ready. Check its logs as messages arrive.

Read Definitions and installations next to decide which settings belong in XML. Then use the chapter for your protocol and the XML reference for its options.