config

Editing config

Default configuration file

{
  "ConfigVersion": "1.0",
  "Server": "mqtt.example.com",
  "Protocol": "mqtt",
  "Port": "auto-ha",
  "SocketPath": "/",
  "Username": "screensleeper",
  "Password": "yourpassword",
  "AutoConnect": true,
  "AllowBadSSL": false,
  "Triggers": [
    {
      "Topic": "my_pc/sleep/set",
      "Payload": "on",
      "Action": "Lock;ScreenOff"
    }
  ]
}

ConfigVersion

  "ConfigVersion": "1.0",

No other valid values. To allow easier forward compatibility.

Server

  "Server": "mqtt.example.com",

MQTT server address.

If the server ends with "example.com", no attempt will be made to autoconnect.

If you have a complete uri to connect to, such as wss://server.example.com:443/example-mqtt/, you may have to break it into parts. This example is broken up into Protocol://Server:Port/SocketPath, so the start of the config file becomes:

{
  "ConfigVersion": "1.0",
  "Server": "server.example.com",
  "Protocol": "wss",
  "Port": "443",
  "SocketPath": "/example-mqtt/",

Protocol

  "Protocol": "mqtt",

Valid protocol options are: mqtt, mqtts, ws, wss

ws and wss use a WebSocket connection.

mqtts and wss use TLS/SSL. It should not connect to a non-secure connection when one of these options is chosen, but I have not verified this to be true. See also: AllowBadSSL

See also:

• if AllowBadSSL is true, TLS/SSL connections will still be allowed for invalid or self-signed certificates.
• Port may change depending on protocol chosen (if it's set to an auto option)
• use SocketPath to specify the uri path for WebSocket connections (ws and wss).

Port

  "Port": "auto-ha",

SocketPath

  "SocketPath": "/",

For WebSocket connections (ws and wss), this is where the mqtt websocket socket is located. e.g. if the server is at "wss://example.com/server/mqtt/", then SocketPath is "/server/mqtt/"

Note: the initial / is optional and is ignored.

Only used for WebSocket connections. Setting is ignored for mqtt and mqtts connections.

See also:

• Protocol
• Topic also looks like a path but is different.

Username

  "Username": "screensleeper",

MQTT username.

See also:

• mosquitto login — making a separate login for Mosquitto MQTT Broker in Home Assistant

Password

  "Password": "yourpassword",

MQTT server password.

For security, as you're storing it in plain text, please do not use a high value password for the MQTT account.

AutoConnect

  "AutoConnect": true,

if true — automatically connect when ScreenSleeper starts. Note: Won't attempt to connect if server is "example.com" or ends with ".example.com".

Set to false to only connect manually.

AllowBadSSL

  "AllowBadSSL": false,

If set to true then when using a TLS/SSL protocol, namely mqtts or wss, accept self-signed or invalid certificates. Useful for your local mqtt server if you haven't worked out a trick to get a certificate for its local-network-pointing domain name.

Triggers

  "Triggers": [

Start of the trigger and action list.

Topic

      "Topic": "my_pc/sleep/set",

The MQTT topic to watch. Wildcards are not (yet) supported.

Payload

      "Payload": "on",

What value the topic must have to trigger the action. RegEx and JQ are not supported.

Action

      "Action": "Lock;ScreenOff"

Action to take when topic is seen with payload

• Lock — go into the Windows lock screen, requiring the user to authenticate to continue using the PC
• ScreenOff — sleep the monitor(s) until woken again (from the mouse is moving or pressing a key)
• ScreenOn — attempt to wake up the monitor(s) by emulating moving the mouse
• Lock;ScreenOff — lock and sleep the screen.

The actions are case sensitive. More may be added in future.

Multiple triggers example

  "Triggers": [
    {
      "Topic": "my_pc/sleep/set",
      "Payload": "off"
      "Action": "ScreenOff",
    },
    {
      "Topic": "my_pc/sleep/set",
      "Payload": "on"
      "Action": "ScreenOn",
    }
  ]