The forwarding bridge server (subsequently referred to as 'server') is designed as a companion to SmartThings Edge drivers that (1) need to send HTTP requests to destinations outside of the LAN, and/or (2) need to be able to receive extemperaneous HTTP messages issued by LAN-based devices and applications.
The server itself is simply a Python script that can be run on any 'always on' Windows/Linux/Mac/Raspberry Pi computer. The server is provided as a 3.7x Python source script, a Windows executable program file, or a Raspberry Pi OS executable program file. It can read an optional configuration file created by the user (see below).
The server includes these capabilities:
A limitation of Edge drivers is that the hub platform allows them to communicate to only local IP addresses. This excludes any internet requests or other external RESTful API calls, for example. With this solution, an Edge driver can send a request to the server to be forwarded outside the LAN, which the server will do and return the response back to the requesting Edge driver. (My Web Requestor https://github.com/toddaustin07/webrequestor devices can also be used to initiate these requests)
Please be aware that the server currently does NOT forward an http request data body - only the request head. This may be added as a future enhancement depending on community requirements.
An additional feature of the server is that it recognizes requests being forwarded to the SmartThings RESTful API, and using the Bearer Token configured by the user, can forward those requests and return the response, allowing Edge drivers access to any SmartThings API call. For example, this can allow a driver to get the device status of ANY SmartThings device, and use it in its logic - allowing it to perform SmartApp-like functions.
Edge drivers cannot use any specific port, so this makes it difficult for other LAN-based configurable devices or applications to be able to send messages directly TO an Edge driver without first establishing a unique peer-to-peer or client/server link initiated by the Edge driver. This is possible, but requires more custom coding on both ends to make it work (discovery, monitoring connection, managing change, etc.).
This server offers a simpler solution: an Edge driver 'registers' with the server what LAN IP address it is interested in getting messages from. The LAN device or application is then configured to send its messages to the server (which has a fixed IP/port number). Then when the server receives those messages, it looks up who is registered to receive them, and then forwards them to the appropriate port number on the SmartThings hub. If/when the Edge driver's assigned port number changes, it simply re-registers the new port number with the server. No configuration change is needed at the LAN device or application. (A static IP address is typically recommended for the physical device or application.)
A SmartThings Edge driver to provide weather data uses this bridge server to provide current weather conditions and weather forecasts. The data is retrieved from various internet weather sources that publish access APIs.
Both of the following two example use cases can be implemented, with this bridge server, using my Edge driver for LAN-based motion sensors (https://github.com/toddaustin07/lanmotion).
There is currently no official local integration of Shelly's wifi Motion Sensors with SmartThings. There are cloud integrations available for other Shelly devices, but as of this writing there are none that support their motion sensor product. These devices can be configured to send an HTTP message to a given IP/Port whenever motion or tampering is detected. With this solution, the device can be configured to send these messages to the server, which will then forward them to registered Edge drivers.
The Blue Iris server allows for configuring actions for a camera whenever it detects motion. These actions can include a web request. Today, this is typically directed at a cloud-based SmartApp for SmartThings integration. But with this solution, the web requests can be directed to the bridge server and forwarded to an Edge driver for 100% local execution.
Note that the forwarding bridge server can be run on the same machine as the Blue Iris server itself.
Another example of an application that can leverage the bridge server to send messages to an Edge driver is my experimental phone tracker app that is available here-> https://github.com/toddaustin07/phonepresence
This application monitors the presence of a cellphone on the home LAN and reports updates back to a LANPresence Edge driver to provide SmartThings presence devices representing the present/away state of the cellphone(s).
This application runs on an always-on computer on your LAN and issues ping messages to see if the device at the specified IP is answering. The results are forwarded to a SmartThings Edge LAN presence driver (available on my test channel).
Any LAN-based device or application that can be configured to send an HTTP request can trigger an Edge button device for invoking SmartThings automation routines and Rules. This provides a super-simple way of connecting LAN-based things locally to SmartThings without having the burden of coding a complicated communications interface. This can easily be expanded to other device types beyond buttons (lights, switches, thermostats, etc.)
See the Edge driver available here -> https://github.com/toddaustin07/lantrigger
This application comes in three forms:
- edgebridge.py: Python 3.x script (for any OS platform supporting Python 3)
- edgebridge.exe: Windows executable (built for Windows 10)
- edgebridge4pi: Raspberry Pi executable (for OS = Raspbian GNU/Linux 10 (buster), CPU = ARMv7)
If you have a Raspberry Pi with Python 3.x you can run the Python script, but if you don't have Python 3.x, you can use the executable.
Download the Python script or applicable executable file to a folder on your computer. You can start it manually or preferrably, configure your computer to auto start the program as a service whenever it reboots.
If you want to change the default port number of the server (8088), you can do so by creating a configuration file which will be read when the server is started. This config file can also be used to provide your SmartThings Bearer Token if you plan to do any SmartThings API calls. The format of the file is as follows:
[config]
Server_Port = nnnnn
SmartThings_Bearer_Token = xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
This configuration file is optional.
On Windows, Mac or Linux with Python 3.x available, start the server by this command:
python3 edgebridge.py
On Windows, start the server by running the downloaded executable:
edgebridge
On a Raspberry Pi, before you can run the file you downloaded, you need to change the file permissions so it is executable, using the first command below. Then you can start the server anytime thereafter using the second command below:
chmod +x edgebridge4pi
./edgebridge4pi
A good option is to run the bridge server in a window where you can monitor the output messages. You may want to log them permanently to a file as well.
This section is for Edge driver developers or those configuring Web Requestor URLs that use the Bridge Server.
The server uses a simple RESTful API to accept commands from SmartThings Edge drivers.
For purposes of the examples below, we'll assume the server is located at 192.168.1.140:8088.
Scenario: The Edge driver wants the server to forward an HTTP request to somewhere outside the LAN
The Edge driver would issue the following HTTP request to the fowarding bridge server:
[GET | POST] http://192.168.1.140:8088/api/forward?url=<URL string>
URL string can be any valid URL including parameters. Examples:
- http://www.websitename.com
- https://http-bin.org/post?key1=key1value&key2=key2value
- https://api.smartthings.com/v1/devices/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/components/main/capabilities/switch/status
POST http://192.168.1.140:8088/api/forward?url=https://http-bin.org/post?key1=key1value&key2=key2value
GET http://192.168.1.140:8088/api/forward?url=https://api.smartthings.com/v1/devices/80e99446-a656-41e2-9db7-3981f7c0e126/components/main/capabilities/switch/status
GET http://192.168.1.140:8088/api/forward?url=https://api.wheretheiss.at/v1/satellites/25544
GET http://192.168.1.140:8088/api/forward?url=https://opendata.fmi.fi/wfs?service=WFS&version=2.0.0&request=getFeature&storedquery_id=fmi::observations::weather::timevaluepair&place=helsinki
Scenario: The Edge driver wants to receive web requests from a LAN-based device or application
The Edge driver sends an HTTP request to the server to register a specific device/app address from which it wants to receive messages:
POST http://192.168.1.140:8088/api/register?devaddr=<address of device/app to listen to>&hubaddr=<hub IP:port in use by the driver>&edgeid=<Edge device.id>
DELETE http://192.168.1.140:8088/api/register?devaddr=<address of device/app to stop listening to>&hubaddr=<hub IP:port in use by the driver>&edgeid=<Edge device.id>
devaddr can optionally include a port number. Examples:
- 192.168.1.150
- 192.168.1.140:2345
hubaddr MUST include the port number:
- 192.168.1.107:31732
edgeid must be in the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx; obtained within Edge driver with 'device.id'
POST http://192.168.1.140:8088/api/register?devaddr=192.168.1.150&hubaddr=192.168.1.107:31732&edgeid=3894BE52-09E8-4CFD-AD5C-580DE59B6873
Once the Edge driver successfully registers with the Bridge Server, the device/app that wants to get a message to a driver simply configures its GET or POST HTTP request to go to the Bridge Server itself. Once received by the Bridge Server, if the source IP address matches an entry in its registration table, then the message will be automatically forwarded to the registered Edge driver. In this way, the device/app never needs to know the hub IP address or driver port number.
A hidden file '.registrations' is maintained by the server to keep a persistant list of driver registrations. Occassionally, Edge drivers or Edge devices may get deleted without issuing a delete registration request to the server. As a result, orphaned registrations can exist. However the server will periodically scrub these when it repeatedly fails to reach the registered driver. Applicable scrub messages will be displayed by the server when this occurs and should be considered normal.