myStrom - fcorthay/xPL GitHub Wiki

The myStrom devices start operating on a standalone Wi-Fi network. Once connected to a device, one can set it up to join a local Wi-Fi network. This being done, the devices are accessed via the myStrom REST API.

Table of Contents

Button

The button is characterized by its MAC address which, on the older devices, is found on the back of it. The first 3 bytes are the Organizationally Unique Identifier (OUI) which can be 5c:cf:7f or bc:ff:4d, and the last 3 bytes are the device's identifier. In the example to come, this identifier will be 0c:c6:d1, which has to be updated in each case.

Local Wi-Fi

In order to work in the home, the button has to be connected to the local Wi-Fi.

Using the app

Start the app. Ask to add a new button and follow the instructions.

From a computer

Install ARP scanning tool: 

sudo apt install -y arp-scan

To discover the myStrom button, press on it until it starts to blink. On a computer with a Wi-Fi interface, find its startup network: 

nmcli dev wifi
You should discover a network with Service Set IDentifier (SSID) my-button-0CC6D1.

 

Change your Wi-Fi network to that one and check your IP address: 

ifconfig | grep ^w
ifconfig wlp1s0
Your IP address should be 192.168.254.2.

 

Get info from the button: 

curl -i -X GET http://192.168.254.1/api/v1/info

Specify the network the button has to join (adapt network_name and password): 

curl -i -X POST -d '{"ssid":"network_name", "passwd":"password"}' http://192.168.254.1/api/v1/connect
The button will join the local network and the network with SSID my-button-0CC6D1 will disappear.

Button setup

The button rapidly goes into sleep mode as it runs on batteries. It has to be activated in order to respond to accesses and requests This is done:

  • by a 2 second button press for a button
  • by removing and reinserting a battery for a button+
Login back to your local Wi-Fi network:

Check the name of your wireless interface and adapt WIFI_INTERFACE: 

sudo ifconfig

WIFI_INTERFACE='wlo1'

Find the button (you might have to repeat some of the commands several times): 

BUTTON_OUI='5c:cf:7f'
BUTTON_OUI='bc:ff:4d'
sudo arp-scan -l  2>/dev/null | grep $BUTTON_OUI

BUTTON_MAC_ADDRESS=`sudo arp-scan -lI $WIFI_INTERFACE 2>/dev/null | grep $BUTTON_OUI | sed -e 's/\t/ /g' | cut -d ' ' -f 2` ; echo "Button MAC address is $BUTTON_MAC_ADDRESS"

BUTTON_IP_ADDRESS=`sudo arp-scan -lI $WIFI_INTERFACE 2>/dev/null | grep $BUTTON_MAC_ADDRESS | sed -e 's/\t/ /g' | cut -d ' ' -f 1` ; echo "Button IP address is $BUTTON_IP_ADDRESS"

ping -c 4 $BUTTON_IP_ADDRESS
sudo arp -n | grep $BUTTON_IP_ADDRESS
curl -X GET http://$BUTTON_IP_ADDRESS/api/v1/info && echo
curl -X GET http://$BUTTON_IP_ADDRESS/api/v1/device && echo
curl -X GET http://$BUTTON_IP_ADDRESS/api/v1/actions && echo

Setup button actions: 

SERVER_IP=192.168.1.5
SERVER_PORT=8002

ping -c 4 $BUTTON_IP_ADDRESS
BUTTON_MAC_ADDRESS=`sudo arp -n | grep "$BUTTON_IP_ADDRESS" | head -n 1 | sed -e 's/\s\+/ /g' | cut -d ' ' -f 3`
BUTTON_ID=`echo $BUTTON_MAC_ADDRESS | tr -d ':' | tr '[:lower:]' '[:upper:]' | cut -c 7-`
echo "Button id of \"$BUTTON_MAC_ADDRESS\" is \"$BUTTON_ID\""

curl --request POST "http://$BUTTON_IP_ADDRESS/api/v1/action/single" --data-raw "post://$SERVER_IP:$SERVER_PORT/myStrom/button/$BUTTON_ID/single"
curl --request POST "http://$BUTTON_IP_ADDRESS/api/v1/action/double" --data-raw "post://$SERVER_IP:$SERVER_PORT/myStrom/button/$BUTTON_ID/double"
curl --request POST "http://$BUTTON_IP_ADDRESS/api/v1/action/long" --data-raw "post://$SERVER_IP:$SERVER_PORT/myStrom/button/$BUTTON_ID/long"
curl --request POST "http://$BUTTON_IP_ADDRESS/api/v1/action/touch" --data-raw "post://$SERVER_IP:$SERVER_PORT/myStrom/button/$BUTTON_ID/touch"

Check button actions: 

curl --request GET "http://$BUTTON_IP_ADDRESS/api/v1/action" && echo
curl --request GET "http://$BUTTON_IP_ADDRESS/api/v1/action/single" && echo
curl --request GET "http://$BUTTON_IP_ADDRESS/api/v1/action/double" && echo
curl --request GET "http://$BUTTON_IP_ADDRESS/api/v1/action/long" && echo

For a button+ (with 4 switches): 

press='generic'
for index in $(seq 1 4) ; do
  curl --request POST "http://$BUTTON_IP_ADDRESS/api/v1/action/btn$index/$press" --data-raw "post://$SERVER_IP:$SERVER_PORT/myStrom/button/$BUTTON_ID/$press$index"
done

curl --request GET "http://$BUTTON_IP_ADDRESS/api/v1/actions" | jq
curl --request GET "http://$BUTTON_IP_ADDRESS/api/v1/action/btn1" | jq
curl --request GET "http://$BUTTON_IP_ADDRESS/api/v1/action/btn1/single" | jq

With this the button :

  • acts as an HTTP REST server to provide device specific information
  • acts as an HTTP REST client to sent requests when it is being activated

HTTP service

The xPL REST interface implements an HTTP server to receive the button requests upon press and to forward the in the form of xPL messages. it is found as central/xpl-rest.py.

If the service is not already running, start it with : 

XPL_BASE_DIR=~/Controls/xPL
$XPL_BASE_DIR/central/xpl-rest.py

It can be tested in a web browser with the URL (adapt server and port) : 

http://192.168.1.5:8002/myStrom/button/0CC6D1/single

It can also be tested in a terminal window (adapt server and port) : 

curl -X GET 'http://192.168.1.5:8002/myStrom/button/0CC6D1/double'
curl -X POST 'http://192.168.1.5:8002/myStrom/button/0CC6D1/double'

And obviously also directly from a myStrom button.

All these accesses fire an xPL message which can be monitored by xPL-base/xpl-monitor.py.

The xPL central control service allows to automatically send further xPL commands based on the reception of the xPL REST button message.

Switch

In order to work in the home, the button has to be connected to the local Wi-Fi.

Look on the back of the switch and find its MAC address. Here we will use the address B48A0AAFD1D8. The Organizationally Unique Identifier (OUI) B4-8A-0A is attributed to Espressif.

Connect to wi-fi

Using the app

Start the app. Ask to add a new switch and follow the instructions.

Using a computer

Check the explanation for a button above.

Test the switch

Search for the switch's IP address: 

SWITCH_MAC_ADDRESS='b4:8a:0a:af:d1:d8'
SWITCH_IP_ADDRESS=''
while [ -z "$SWITCH_IP_ADDRESS" ] ; do
  echo -n '.'
  SWITCH_IP_ADDRESS=`sudo arp-scan -l 2>/dev/null | grep $SWITCH_MAC_ADDRESS`
done
echo
SWITCH_IP_ADDRESS=`echo $SWITCH_IP_ADDRESS | sed -e 's/\t/ /g' | cut -d ' ' -f 1`
echo "Switch \"$SWITCH_MAC_ADDRESS\" IP address is $SWITCH_IP_ADDRESS"
ping -c 1 $SWITCH_IP_ADDRESS > /dev/null
One needs the while loop as the device isn't always found.

 

The ending ping command makes sure that the IP address is found in the ARP table. With this, one can examine the device with: 

arp -n | grep $SWITCH_MAC_ADDRESS
ip neighbour | grep $SWITCH_MAC_ADDRESS

Search for the switch's settings: 

curl -g "http://$SWITCH_IP_ADDRESS/api/v1/monitor" && echo

Play with the switch: 

curl -g "http://$SWITCH_IP_ADDRESS/relay?state=1"
curl -g "http://$SWITCH_IP_ADDRESS/relay?state=0"
curl -g "http://$SWITCH_IP_ADDRESS/toggle" && echo
curl -g --request POST "http://$SWITCH_IP_ADDRESS/timer?mode=toggle&time=5"
curl -g "http://$SWITCH_IP_ADDRESS/report" && echo

Set IP address

One can set a fixed IP address or ask fro DNS in the web page served by the switch at its present IP address.

⚠️ **GitHub.com Fallback** ⚠️