Skip to content

Commit e202d71

Browse files
sebastienvermeillesebastienvermeille
committed
Setup Docusaurus documentation
1 parent df82cdf commit e202d71

62 files changed

Lines changed: 21153 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitignore‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Dependencies
2+
/node_modules
3+
4+
# Production
5+
/build
6+
7+
# Generated files
8+
.docusaurus
9+
.cache-loader
10+
11+
# Misc
12+
.DS_Store
13+
.env.local
14+
.env.development.local
15+
.env.test.local
16+
.env.production.local
17+
18+
npm-debug.log*
19+
yarn-debug.log*
20+
yarn-error.log*

‎README.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Documentation
2+
3+
This documentation website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
4+
5+
### Installation
6+
7+
```
8+
$ yarn
9+
```
10+
11+
### Local Development
12+
13+
```
14+
$ yarn start
15+
```
16+
17+
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
18+
19+
### Build
20+
21+
```
22+
$ yarn build
23+
```
24+
25+
This command generates static content into the `build` directory and can be served using any static contents hosting service.
26+
27+
28+
### Deployment
29+
30+
Deployment is automated by `.github/workflows/deploy-doc.yml` to GitHub pages.

‎docs/advanced/architecture.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
---
2+
title: Architecture
3+
sidebar_position: 7
4+
---
5+
import Centered from '@site/src/components/Centered';
6+
7+
# Architecture
8+
9+
## Software components
10+
There are 3 software components written for the NSPanel Manager project:
11+
12+
* **Web interface**: The web interface that you interact with is built on top of the Django framework. This software gives
13+
the user an interface to interact and configure the project with. This software also manages the database with settings.
14+
* **MQTT Manager**: There is a second software running in the background on the NSPanel Manager container that
15+
hosts the web interface. This component is named "MQTTManager". The MQTTManager handles all things with
16+
MQTT. It loads the config from the web interface via the API and then processes all commands from panels, state
17+
updates from Home Assistant and OpenHAB and so on. It’s basically the glue that makes the panel’s actions affect
18+
Home Assistant and OpenHAB. The MQTTManager is also the software that send state updates from Home Assistant
19+
and OpenHAB to the panels when changes occur.
20+
* **The NSPanel firmware**: The firmware written for the NSPanel has been specifically designed to be as response
21+
and easy to use as possible. The firmware handles all communication with the TFT (Nextion) display and with
22+
MQTTManager via MQTT.
23+
24+
## Data flow
25+
26+
<Centered>
27+
```mermaid
28+
flowchart TD
29+
HAS(Home Assistant/OpenHAB)
30+
NSPM(NSPanel Manager container)
31+
MQTT(MQTT Server)
32+
NSP1(NSPanel 1)
33+
NSP2(NSPanel 2)
34+
HAS <--> NSPM
35+
NSPM <--> NSP1
36+
NSPM <--> NSP2
37+
MQTT <--> HAS
38+
MQTT <--> NSPM
39+
MQTT <--> NSP1
40+
MQTT <--> NSP2
41+
```
42+
</Centered>
43+
44+
The data flow within NSPanel Manager might look intimidating but it’s not that bad. Below is an explanation of all the
45+
arrows above.
46+
47+
### Home Assistant and/or OpenHAB to/from NSPanel Manager container
48+
49+
There is two types of traffic flowing between these nodes:
50+
* **Websocket**: A websocket connection is setup in order for the NSPanel Manager container to receive entity updates
51+
from Home Assistant and/or OpenHAB but also to sent entity commands (E.. turn light X on to 20%). A websocket
52+
is used to speed up the communication and also to not have to poll the home automation software for information.
53+
* **HTTP GET API**: The usual HTTP GET API is also used. This is used when adding entities to a room, as an
54+
example. When pressing the "Add new light" button, the NSPanel Manager container will make an HTTP GET request
55+
to gather all available entities and then send them back to the client (browser) so that the user may choose what
56+
entity to add to the room.
57+
58+
### NSPanel Manager container to/from MQTT
59+
60+
MQTT is used to send updated entity states received from the home automation software out to all NSPanels and also
61+
receive states and commands from NSPanels.
62+
63+
### Home Assistant and/or OpenHAB to/from MQTT
64+
65+
Home Assistant and OpenHAB can leverage the MQTT integration through "Home Assistant MQTT Auto-discovery" (which
66+
OpenHAB can also use) to auto-discover NSPanels and automatically register entities for panel temperature reading, panel
67+
relays, screen state and so on.
68+
69+
### NSPanel Manager container to/from NSPanels
70+
71+
The configuration of lights, scenes and so on does not reside on each panel. The panel only has locally the bare minimum
72+
configuration for setup. When the panel starts and has connected to WiFi it will do a HTTP GET request to the NSPanel
73+
Manager container in order to receive all configuration of entities, screen brightness and really, all settings
74+
available in the NSPanel Manager web interface.
75+
76+
### MQTT to/from NSPanels
77+
78+
Each NSPanel send states (E.g. temperature) and commands (E.g. turning on a light) over MQTT for the NSPanel Manager
79+
container to pickup.
80+
81+
The panel also receives commands, E.g. turn on relay 1, turn on screen and so on.
82+
83+
:::info
84+
The complete list of MQTT topics is documented [here](./mqtt-topics).
85+
:::

‎docs/advanced/logs.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
title: Logs
3+
sidebar_position: 5
4+
---
5+
import CenteredImage from '@site/src/components/CenteredImage';
6+
7+
# Logs
8+
9+
While logs are normally sent over MQTT, any logs that are created before WiFi-connection are sent out on Serial.
10+
If you wish to see the logs going over MQTT, you can look at the topic `nspanel/<panel name>/log`.
11+
12+
If you wish to look at the logs going over serial, you can use programs like Putty.
13+
14+
Connect to the NSPanel with the serial programmer as usual but don’t connect `IO0` to `GND`.
15+
16+
In Putty enter your serial port in the "Serial line" box and choose baud `115200`.
17+
18+
You should then be able to connect by pressing the "Open"-button.
19+
20+
:::info
21+
On Windows `/dev/ttyUSB0` will have to be replaced by something like `COM4`. If using MacOS or Linux the port
22+
will be something similar to `/dev/ttyUSB0`.
23+
:::
24+
25+
Example:
26+
27+
<CenteredImage src="/images/doc/putty_serial.png" alt="Connecting to Serial with Putty" figureNumber={10} />

‎docs/advanced/mqtt-topics.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
title: MQTT Topics
3+
sidebar_position: 10
4+
---
5+
import Centered from '@site/src/components/Centered';
6+
7+
# MQTT Topics
8+
9+
Below table is a description of all MQTT topics that might be of use by a user. Replace `<panel_name>` with the friendly
10+
name of your NSPanel:
11+
12+
| Topic | Payload | Description |
13+
|-----------------------------------------------|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
14+
| nspanel/\<panel_name\>/screen_cmd | 1 or 0 | Send a 1 or 0 to turn on/off the display. |
15+
| nspanel/\<panel_name\>/screen_state | 1 or 0 | Current state of the screen. |
16+
| nspanel/\<panel_name\>/brightness | 1 to 100 | Control the brightness of the screen. |
17+
| nspanel/\<panel_name\>/brightness_screensaver | 0 to 100 | Control the brightness of the screensaver. |
18+
| nspanel/\<panel_name\>/r1_cmd | 1 or 0 | Send a 1 or 0 to turn on/off relay 1. |
19+
| nspanel/\<panel_name\>/r1_state | 1 or 0 | The current state of relay 1. |
20+
| nspanel/\<panel_name\>/r2_cmd | 1 or 0 | Send a 1 or 0 to turn on/off relay 2. |
21+
| nspanel/\<panel_name\>/r2_state | 1 or 0 | The current state of relay 2. |
22+
| nspanel/\<panel_name\>/temperature_state | Current temperature | The current temperature reading. |
23+
| nspanel/\<panel_name\>/screensaver_mode | 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 |
24+
| nspanel/\<panel_name\>/log | Log message | The panel will send live logs on this topic. |
25+
26+
There are more topics that are used internally, these are:
27+
28+
29+
| Topic | Payload | Description |
30+
|------------------------------------------------------|----------------------------|---------------------------------------------------------------------------------------------------------|
31+
| nspanel/entities/\<type\>/\<id\>/state_\<attribute\> | The value of the attribute | An update of entity state value sent out by MQTTManager. Example:nspanel/entities/light/42/state_kelvin |
32+
| nspanel/status/time | Time as a string | Current time sent by MQTTManager. |
33+
| nspanel/status/weather | JSON | A JSON representation of the current weather and weather forecast. |
34+
| nspanel/\<panel_name\>/status_report | JSON | JSON payload with current state of the panel. |
35+
| nspanel/\<panel_name\>/status | JSON | JSON payload with current online/offline state of the panel. |
36+
| nspanel/\<panel_name\>/command | JSON | JSON payload with a command for the panel to execute. |
37+
| nspanel/mqttmanager/command | JSON | JSON payload from panel with a command for MQTTManager to perform. |
38+

‎docs/getting-started/configuration.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
title: Configure NSPanel Manager
3+
sidebar_position: 6
4+
---
5+
import CenteredImage from '@site/src/components/CenteredImage';
6+
7+
# Configure NSPanel Manager
8+
9+
## Access NSPanel Manager web interface
10+
11+
For docker users, simply connect to: `http://your-server-ip:8000`
12+
13+
For Home Assistant users having installed the [Home Assistant Add-on](./install/installation-guide-home-assistant), TODO: document
14+
15+
## Initial setup
16+
17+
When first logging into the NSPanel Manager web interface you will be greeted by a configuration wizard:
18+
19+
<CenteredImage src="/images/doc/initial_setup_popup.png" alt="Configuration wizard" figureNumber={1} />
20+
21+
1. Click **next**
22+
2. Fill up requested information
23+
24+
This guide will help you set up the required items in order to have a functional setup.
25+
26+
The following is a walkthrough of what to enter:
27+
* **Manager config**
28+
* **Manager address** - This address is sent to NSPanel over MQTT when the request to connect with a manager.
29+
This can be loaded from the URL using the "Load from URL" button. This address needs to be reachable by all
30+
NSPanels.
31+
* **Manager port** - This port that will be used to connect to the address above.
32+
33+
* **MQTT config**
34+
* **MQTT address** - The address to your MQTT broker. If you are running your MQTT broker as an addon to
35+
Home Assistant, enter you Home Assistant address (only IP).
36+
* **MQTT port** - The port to connect to your MQTT broker.
37+
* **MQTT username** - The username to authenticate to your MQTT broker. Leave empty if you don´t use authentication.
38+
* **MQTT password** - The password to authenticate to your MQTT broker. Leave empty if you don´t use authentication.
39+
40+
* **Home Assistant config (optional)**
41+
* **Home Assistant address** - The address to your Home Assistant instance. This address should include "http"
42+
or "https" in the beginning and ":8123" (change to your port) at the end.
43+
* **Home Assistant token** - The long lived access token used to authenticate to Home Assistant.
44+
45+
* **OpenHAB (optional)**
46+
* **OpenHAB address** - The address to your OpenHAB instance. This address should include "http" or "https" in
47+
the beginning and ":8123" (change to your port) at the end.
48+
* **OpenHAB token** - The access token used to authenticate to OpenHAB.
49+
50+
3. Congrats you have finished the initial setup and you can now use NSPanel Manager.
51+
4. If you are willing to learn more about the Web interface, please read [this](./../web-interface).

0 commit comments

Comments
 (0)