ThingWorx WebSocket-based Edge MicroServer (WS EMS) and Lua Script Resource (LSR) > WS EMS and ThingWorx Platform > The Connection Sequence
The Connection Sequence
The process of connecting to a ThingWorx platform instance consists of three main steps: Connect, Authenticate, and Bind. The WS EMS performs the first two steps. Then, the WS EMS works with the Lua Script Resource or a custom application to perform the third step. Here are the steps in more detail:
1. Connect — The WS EMS opens a physical WebSocket to a ThingWorx platform instance, using the host and port specified in its configuration file. If configured, SSL/TLS is negotiated at this time.
2. Authenticate — The WS EMS sends an authentication message to the ThingWorx platform instance. This message must contain an Application Key that was previously generated by an administrator user.
Upon successful authentication, the WS EMS can interact with the ThingWorx platform instance, according to the permissions applied to its Application Key. For the WS EMS, this implies that any client that makes HTTP calls to its REST interface can access functionality on the ThingWorx platform instance. For this reason, the WS EMS is set by default to listen for HTTP connections on localhost (port 8000). You can change this listening port in the configuration file for the WS EMS.
At this point, the WS EMS can make requests to the ThingWorx platform instance and interact with it, much like an HTTP client can interact with the REST interface of the platform instance, but the instance cannot direct requests to the Edge device.
3. Bind — To enable the ThingWorx platform instance to send requests to the WS EMS, the WS EMS works with the Lua Script Resource (or custom application) to send a BIND message to the ThingWorx platform instance on behalf of the devices. Note that this step is optional, if you do not want the devices to receive and process requests from the platform instance. It is required if you want to transfer files from the platform instance to your devices or if you want to use tunneling.
The BIND message can contain one or more names or identifiers for the devices. Note that corresponding remote things must have been created on the ThingWorx platform instance to represent your edge devices. Remote things are things that are created using the RemoteThing thing template (or one of its derivatives) in ThingWorx platform. When it receives the BIND message, the platform instance associates the matching remote things that it has with the WebSocket that received the BIND message. This association allows the instance to use the WebSocket to send requests to the edge devices, and update the isConnected and lastConnection time properties for the corresponding remote things on the ThingWorx platform instance.
The WS EMS can send an UNBIND message to the ThingWorx platform instance that removes the association between the remote things on the instance and the WebSocket. The isConnected property is then updated to false.