Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 24 additions & 3 deletions docs/advanced/logs.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,23 @@ import CenteredImage from '@site/src/components/CenteredImage';

# Logs

While logs are normally sent over MQTT, any logs that are created before WiFi-connection are sent out on Serial.
If you wish to see the logs going over MQTT, you can look at the topic `nspanel/<panel name>/log`.
Once the NSPanel is connected to MQTT, it sends its logs on the topic `nspanel/<mac>/log`, where `<mac>` is the MAC address of the panel.
These are the logs you see in the live log view on the NSPanel page in the web interface, and the log level is set on the
settings page on the panel itself.

Logs created while the panel isn't connected to MQTT, for example during boot or before WiFi has connected, can't reach the
manager, so they're written to the serial port instead.

## Serial log setting

The **Serial log** setting on the panel's own settings page controls when log lines are also written to the serial port:

- **Auto (only while not connected to MQTT)** - The default. Lines go to the serial port only while they can't be sent over
MQTT. Writing to the serial port slows the panel down, so it is skipped once the logs reach the manager.
- **Always** - Every line is written to the serial port as well. Useful when debugging with a serial cable attached.
- **Never** - Nothing is written to the serial port.

## Read the serial log

If you wish to look at the logs going over serial, you can use programs like Putty.

Expand All @@ -24,4 +39,10 @@ will be something similar to `/dev/ttyUSB0`.

Example:

<CenteredImage src="/images/doc/putty_serial.png" alt="Connecting to Serial with Putty" figureNumber={10} />
<CenteredImage src="/images/doc/putty_serial.png" alt="Connecting to Serial with Putty" figureNumber={10} />

## Event loop watchdog

If the panel stops responding to touches while it still shows as online in the manager, look for `LoopWatchdog` lines in its
log. The panel logs these when its main event loop has stalled for 15 seconds or more: one line per task, each with a backtrace.
They are useful to include in a bug report.
6 changes: 4 additions & 2 deletions docs/advanced/mqtt-topics.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,22 +26,24 @@ Below table is a description of all MQTT topics that might be of use by a user.
| nspanel/\<mac\>/screensaver_mode_cmd | screensaver mode | Select what screensaver to display <br/> Choose from the following: <br/>- with_background<br/>-without_background<br/>-datetime_with_background<br/>-datetime_without_background<br/>or no_screensaver |
| nspanel/\<mac\>/screensaver_mode_state | screensaver mode | The currently selected screensaver mode |
| nspanel/\<mac\>/log | Log message | The panel will send live logs on this topic. |
| nspanel/\<mac\>/buzzer_raw_command | Buzzer raw command | The raw command to control the buzzer. |
| nspanel/\<mac\>/buzzer_raw_command | RTTTL string | An RTTTL tune to play on the buzzer. An empty message stops playback. |
| nspanel/\<mac\>/buzzer_mute_cmd | 1 or 0 | Send a 1 or 0 to mute or unmute the sounds configured for panel events. Tunes sent on buzzer_raw_command still play. |
| nspanel/\<mac\>/buzzer_mute_state | 1 or 0 | Whether the event sounds are currently muted. |

Below are more topics that are used internally. Replace `<manager_address>` with the IP address of the manager container.

| Topic | Payload | Description |
| --------------------------------------------------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------- |
| nspanel/mqttmanager\_\<manager_address\>/status/time | Time as a string | Current time sent by MQTTManager. |
| nspanel/mqttmanager\_\<manager_address\>/status/date | Date as a string | Current date sent by MQTTManager. |
| nspanel/mqttmanager\_\<manager_address\>/status/epoch | Unix time (ms) | Current time in milliseconds since the Unix epoch, sent by MQTTManager every minute and whenever a panel comes online. Panels use it to set their clock. Not retained. |
| nspanel/mqttmanager\_\<manager_address\>/status/weather | Protobuf | A protobuf representation of the current weather and weather forecast. |
| nspanel/\<mac\>/status_report | Protobuf | Protobuf payload with current state of the panel. |
| nspanel/\<mac\>/status | JSON | JSON payload with current online/offline state of the panel. |
| nspanel/\<mac\>/command | JSON | JSON payload with a command for the panel to execute. |
| nspanel/mqttmanager\_\<manager_address\>/command | Protobuf | Protobuf payload from panel with a command for MQTTManager to perform. |
| nspanel/mqttmanager\_\<manager_address\>/room/\<room_id\>/state | Protobuf | Protobuf payload from the manager that represents the "Home page" state to display on the NSPanel for the given room. |
| nspanel/mqttmanager\_\<manager_address\>/all_rooms_state | Protobuf | Protobuf payload from the manager that represents the "Home page" state to display on the NSPanel when in "All rooms" mode. |
| nspanel/mqttmanager\_\<manager_address\>/all_rooms_state | Protobuf | Protobuf payload from the manager that represents the "Home page" state to display on the NSPanel when in "All rooms" mode. |
| nspanel/mqttmanager\_\<manager_address\>/entity_pages/\<page_id\>/state | Protobuf | Protobuf payload from the manager that represents the "Entities"/"Scenes" state to display on the NSPanel when. |
| nspanel/mqttmanager\_\<manager_address\>/relay_groups/\<group_id\>/state | 1 or 0 | Current state of the relay group binding 1 for "ON" and 0 for "OFF". |
| nspanel/mqttmanager\_\<manager_address\>/entities/lights/\<light_id\>/state | Protobuf | Current state of the light. |
30 changes: 27 additions & 3 deletions docs/web-interface.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,17 @@ Available options for each individual NSPanel are:
- **Detached mode** - Detached mode controls an entity via your selected home automation platform. Do not however that not all entity types support the toggle mechanism.
- **Custom MQTT** - This mode can be used to send a custom message on a custom MQTT topic.
- **Follow mode** - When the button is pressed the relay is engaged, when the button is release the relay is disconnected.
- **Thermostat (heating) mode** - The panel switches the relay itself to keep the temperature between a lower and an
upper limit. The relay turns on when the temperature falls to the **Relay 1/2 lower temperature** and turns off when it
rises to the **Relay 1/2 upper temperature**.
- **Thermostat (cooling) mode** - As above, but the other way round: the relay turns on when the temperature rises to
the upper temperature and turns off when it falls to the lower temperature.

In both thermostat modes the button doesn't control the relay, and the relay starts off when the panel boots.
The limits are whole degrees, in the same unit the panel shows (Celsius or Fahrenheit).
The panel uses only its own internal temperature sensor, so it doesn't depend on another sensor reporting in.
Be aware that the relay can warm the panel and skew the reading, and that a panel that stops responding also stops
switching the relay.
- **Relay 1/2 default mode** - Select the default mode of the relay when the NSPanel starts.
- **Register relay 1/2** as:
- **Switch** - The relay will be registered to Home Assistant as a switch entity.
Expand Down Expand Up @@ -193,7 +204,7 @@ When adding/editing a thermostat/climate entity you get multiple options of char
- **Home Assistant Entity <Label value="home_assistant"/>** - The home assistant entity to control.
- **Load options from selected Home Assistant entity <Label value="home_assistant"/>** - This button will load all available options from the selected Home Assistant entity and populate the fields below.
- **Temperature item <Label value="openhab"/>** - The item in OpenHAB that controls the target temperature.
- **Step size <Label value="openhab"/>** - When adjusting the temperature, step the temperature by this value.
- **Step size** - When adjusting the temperature, step the temperature by this value. Defaults to 0.5.

Following those settings there will be groups of items/settings to adjust. These are the following:

Expand Down Expand Up @@ -226,6 +237,12 @@ An NSPM button entity is controlled by the NSPanel Manager itself. This button e

It's possible to add relays/switches as controlled entities from the NSPanel. These are simply on/off and can be toggled from the "Entities page" on the NSPanel.

### Delete a room

Press **Delete** on the room page and confirm. The room's entities, scenes and pages are deleted with it, and any panels
in the room are moved to another room.
The last room can't be deleted while panels are assigned to it. Create another room or remove the panels first.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This line is no longer correct. This behavior has been rectified since I stumbled upon that test as it was incorrect behavior. Having no rooms defined at all means that no new panel can register.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you clarify what the behavior is now then, as the behavior it describes seems to match what I'd expect? What happens now if you delete the last room -- doesn't that lead to to the situation you're trying to avoid and reference in the final sentence?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Its no longer possible to delete the last room regardless of if it has any panels or not.


## Relay groups

Relay groups are used to bind multiple NSPanels and relays together so that when one relay in the group changes state,
Expand Down Expand Up @@ -304,8 +321,12 @@ The following options are available:
- **Maximum color temperature** - The maximum kelvin to send to Home Assistant/OpenHAB.
- **Reverse color temperature slider** - Reverse the color temperature sliders on the NSPanel used to control color
temperature on lights.
- **Turn on behavior** - Wether to send color temperature when turning on the light or to simply send the "turn on"
command.
- **Turn on behavior** - What to send when the NSPanel turns on a light that is off:
- **Color temperature** - Turn the light on in color temperature mode, at its last known color temperature, even if it
was last in color (RGB) mode. Choosing a color on the panel still turns it on in that color. This only applies to
lights configured with color temperature support, and only once the light has reported a color temperature.
Until then, the light keeps its own last color temperature.
- **Restore** - Simply send the "turn on" command, so the light comes back however it was before.
- **Raise lights to 100% threshold** - The slider on the NSPanel can be finiky to get to reach the maximum value of
100%. To solve this problem this option can be used to force the value to be 100% above the given value.
- **Minimum button push time (ms)** - The minimum amout of time (in milliseconds) for the physical buttons to be
Expand Down Expand Up @@ -333,6 +354,9 @@ The following options are available:
- **MQTT ignore time (ms)** - Time to wait (in milliseconds) after sending a command over MQTT before allowing
new values to update the screen. This can be raised or lowered to minimize flickering of sliders on the NSPanel.
- **Optistmic mode ** - Replaces "MQTT Ignore time (ms)". When sending a command to set the state of a light or other entity, should we wait for a callback from Home Assistant or OpenHAB that a light has changed before updating the value on the NSPanel (Wait mode) or should we simply be optistmic and assume the values we sent will be set and immideatly update the displayed values on the NSPanel (optistmic mode).
- **Room status backoff time (ms)** - When an entity in a room changes state, how long the manager waits for other changes
to settle before sending the room's new state to the NSPanels (in milliseconds). This avoids flickering when several
lights change at once.
- **"All rooms" status backoff time (ms)** - When a room changes state, how long should the manager wait before recalculating the new state for "All rooms" view/mode on the NSPanel (in milliseconds).
- **"Default light turn on brightess** - When a light has a brightness of 0 and the manager tries to turn it on it will default to this value.

Expand Down