Understanding the Shelly Local API
The Shelly Plus Plug S and similar devices expose a robust local REST API that operates independently of the cloud. By default, these devices listen on port 80 and provide endpoints for status checks, configuration, and command execution. When dealing with network instability or switch unavailability, relying on the local API is far more responsive than polling the cloud service. The core mechanism for sending data out from the device involves the NotifyOnEvent feature, which allows you to define specific triggers based on internal states.
To send a POST request, you must first identify the unique identifier (ID) of the relay or switch component within the plug. This ID is typically 0 for the main relay but can be verified through the device’s JSON status endpoint. Understanding this structure is crucial because the event notifications are tied to specific components rather than the device as a whole.
Configuring Event Notifications via cURL
The most efficient way to configure these events on a Linux machine is using cURL. You will need to interact with the device’s configuration endpoint at /rpc/Shelly.SetConfig. This RPC method allows you to modify the device settings dynamically. The key parameter to adjust is switch:0, specifically its notify_on_event array.
- Identify the IP address of your Shelly Plus Plug. For example,
192.168.1.50. - Determine the URL where your Linux server will receive the POST requests. Let’s assume it is
http://your-linux-server:8080/webhook. - Construct the JSON payload to update the configuration.
The following command demonstrates how to set up the notification:
curl -X POST http://192.168.1.50/rpc/Shelly.SetConfig \
-H "Content-Type: application/json" \
-d '{
"config": {
"switch:0": {
"notify_on_event": [
{
"event": "device_shutdown",
"urls": ["http://your-linux-server:8080/webhook"]
},
{
"event": "relay_off",
"urls": ["http://your-linux-server:8080/webhook"]
}
]
}
}
}'In this example, we are listening for two critical events: device_shutdown and relay_off. The device_shutdown event is particularly useful when the switch becomes unavailable or loses power, as it triggers immediately before the device disconnects from the network. This gives your Linux system a final chance to record the last known state.
Handling Incoming POST Requests on Linux
Once the Shelly device is configured, your Linux server must be ready to accept these incoming connections. You can use simple tools like ncat, ncat from the Nmap suite, or a lightweight Python HTTP server to capture these requests.
If you prefer a quick test without writing complex code, you can use ncat to listen on port 8080:
ncat -l 8080 -kThis command starts a listener that keeps open after each connection (-k), allowing you to see multiple POST requests in real-time. When the Shelly plug sends a notification, you will see the raw HTTP headers and body printed to your terminal. This is invaluable for debugging and verifying that the JSON structure matches your expectations.
For production environments, consider using a more robust solution such as a Node.js script, a Python Flask app, or even a systemd socket unit. These solutions can parse the JSON payload, validate the source IP, and trigger appropriate actions in your home automation ecosystem, such as updating a database or sending an alert.
Troubleshooting Connectivity Issues
If you do not receive the POST requests, there are several common pitfalls to check. First, ensure that your Linux firewall allows incoming traffic on the specified port. Use ufw allow 8080/tcp if you are using UFW, or adjust your iptables rules accordingly.
Second, verify that the Shelly device and your Linux server are on the same subnet. While routing between subnets is possible, local API calls are most reliable when both devices share the same broadcast domain. If you are using HTTPS for your webhook URL, ensure that the Shelly device trusts the certificate presented by your Linux server. Since self-signed certificates are common in local setups, you may need to configure the Shelly device to ignore certificate errors or import the CA certificate.
Additionally, check the device’s log output via the web interface or the /rpc/Shelly.GetStatus endpoint to confirm that the configuration was applied successfully. Look for the notify_on_event field in the response to ensure your URLs are listed correctly.
Security Considerations
Exposing your webhook endpoint to the local network introduces potential security risks. Since Shelly devices do not support authentication for these local API calls, any device on the network can potentially spoof requests. To mitigate this, consider implementing a shared secret in the query parameters of your webhook URL, such as http://your-linux-server:8080/webhook?secret=your_secret_key.
Your Linux application should then validate this secret before processing the request. This simple step prevents unauthorized devices from triggering false alarms or exhausting your resources. Furthermore, restrict access to the webhook endpoint using firewall rules to only allow traffic from the Shelly device’s IP address.
Frequently Asked Questions
How do I find the IP address of my Shelly Plus Plug?
You can discover the IP address by checking your router’s DHCP client list or by using network scanning tools like nmap on your Linux box. Scanning the subnet for open port 80 will quickly identify all active Shelly devices.
Can I send GET requests instead of POST requests?
Yes, the Shelly API supports various HTTP methods for notifications. However, POST is preferred because it allows you to send a JSON payload with detailed status information, whereas GET requests are limited to headers and query parameters.
What happens if the Shelly device loses internet connectivity?
The local API continues to function normally as long as the device remains connected to the local network. Events like relay switches and shutdowns will still trigger POST requests to your local Linux server, ensuring uninterrupted monitoring.
How can I debug the JSON payload sent by the Shelly device?
Use a tool like ncat or a browser-based developer tool to capture the raw HTTP traffic. This allows you to inspect the exact structure of the JSON object, including event type, timestamp, and component ID, ensuring your parser handles it correctly.
Is it safe to use self-signed certificates for HTTPS notifications?
While technically feasible, Shelly devices may reject self-signed certificates by default due to strict TLS validation. It is recommended to use HTTP for local networks unless you have a trusted internal PKI infrastructure that can issue valid certificates for your local domains.