User Guide

After a reboot all output channels are switched on. That way you can use the powerstrip as an ordinary powerstrip in case you’re not interested in its advanced features for a change.
The control program for the powerstrip is started automatically as a service, controlled by systemd. This means that the program will be automatically restarted should it ever crash. I have not witnessed a crass yet, but I don’t guarantee that it will never happen. Keep in mind that all output channels will be switched on after a restart of the powerstrip control software.
When you’ve made some changes in the configuration, either in the main program itself, or in one of the configuration files, you must restart the control software to make those changes effective. You do that by typing sudo systemctl restart powerstrip.service .

All important state changes are logged in /var/log/syslog while the program is running. Output state changes are not logged though.

Telegram is a public service. Therefore it is possible for total strangers to talk to your bot. It goes without saying that it is not desirable to allow changing output states by total strangers. Therefore the program uses a whitelist of allowed users. This whitelist is either maintained in the main program or in the telegram configuration file.
When you get the message "Sorry, I don't know you. 123456789" you must add the given user id to the whitelist and restart the control software. Unauthorized users are also logged in /var/log/syslog, that way you can always check whether you’ve had uninvited visitors

Commanding The Powerstrip

A small set of commands can be given to the powerstrip, either by Telegram or by MQTT. I deliberately kept the command set for both methods the same. However Telegram requires a slash in front of every command, whereas for MQTT I’ve made this slash optional.

Telegram always returns a reply after the execution of a command to the same telegram message. MQTT replies to the topic mqtt_name/stat, so if you’re interested in the replies you should subscribe to that topic before sending commands.
Sending a command over MQTT is done by publishing a message to the topic mqtt_name/control, with the command and parameters as message. Telegram commands which can affect the status of the output channels also publish the resulting status to the above mentioned MQTT topic.

Parameters are separated from a command by at least on space character. In case of the channel list parameter any digit from 1 to 6 is accepted as legal channel. Spaces, commas and dots are ignored while parsing a channel list parameter. Channel numbers can be given in any order, while double channel numbers are ignored.

In case you give the powerstrip an unknown command it will respond with "Sorry, I didn’t get that".

/status

Shows you which output channels are on. Its output looks like any of these lines:

None are on
4 is on
1, 2, 3 are on
1, 2, 3, 4, 5, 6 are on

/ip

Responds with the power strip’s IP address. This might come in handy in case you want to login to the command line interface of the powerstrip.

192.168.1.30

/on channellist

Switches the selected channels on. Other channels don’t change. The channel list is not optional. If the channel list is missing or has illegal characters in it an "Illegal or missing parameter" error is returned and no channels will change state.
The /on command always returns the resulting status of the output channels, just like the /status command does.

/off channellist

Switches the selected channels off. Other channels don’t change. The channel list is not optional. If the channel list is missing or has illegal characters in it an "Illegal or missing parameter" error is returned and no channels will change state.
The /off command always returns the resulting status of the output channels, just like the /status command does.

/toggle channellist

Toggles the selected channels. Other channels don’t change. The channel list is optional for this command. An empty channel list will toggle all output channels. If the channel list has illegal characters in it an "Illegal or missing parameter" error is returned and no channels will change state.
The /toggle command always returns the resulting status of the output channels, just like the /status command does.

/set channellist

Switches the selected channels on. All other channels are switched off. The channel list is optional for this command. An empty channel list will switch all output channels off. If the channel list has illegal characters in it an "Illegal or missing parameter" error is returned and no channels will change state.
The /set command always returns the resulting status of the output channels, just like the /status command does.

/shutdown

This command tells the Raspberry Pi in the powerstrip to shutdown nicely. You could simply pull the plug, like you probably would do with just about any other powerstrip. The file system of the Raspberry Pi is very robust and should survive sudden shutdowns. But it is always safer to send the shutdown command before pulling the plug.
The command responds with "The system will go down in 1 minute." And the event is also logged to /var/log/syslog.
After one minute all output channels will be switched on and the Raspberry Pi will no longer be running. The only way to start the Raspberry Pi again is to power cycle the powerstrip.
An unintended shutdown can be cancelled during this one minute delay by the /cancel command.

/cancel

This command cancels the imminent shutdown previously given by the /shutdown command. It will respond with "Shutdown has been cancelled." The event will also be logged in /var/log/syslog .

/red

Switch the status LED to red. It also publishes "Red LED is on" to the mqtt_name/stat topic.

/orange

Switch the status LED to orange. It also publishes "Orange LED is on" to the mqtt_name/stat topic.

/green

Switch the status LED to green. It also publishes "Green LED is on" to the mqtt_name/stat topic.

/dark

Switch the status LED off. It also publishes "Status LED is off" to the mqtt_name/stat topic.

Status LED

A bi-colour LED normally shows the status of the powerstrip controller. When it neither is connected to Telegram nor to MQTT it will show red. If just one of the services is connected it will show orange. And when both services are connected it shows green.
The colour of the Status LED can be changed by the commands /red, /orange, /green and /dark. However that change is not locked. Should the MQTT service disconnect, for whatever reason, it will show orange again. After a reconnect it will show green again, as expected.