Skip to content

Commit a745229

Browse files
author
Sebastien Vermeille
authored
Import doc from NSPanelManager repository
Doc were splitted into a dedicated repository for easier maintenance
2 parents 767e41d + 89e7495 commit a745229

74 files changed

Lines changed: 21634 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/contribute/documentation/custom-widgets.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
---
2+
title: Custom widgets
3+
sidebar_position: 2
4+
---
5+
import Tabs from '@theme/Tabs';
6+
import TabItem from '@theme/TabItem';
7+
import CenteredImage from '@site/src/components/CenteredImage';
8+
import Centered from '@site/src/components/Centered';
9+
import YouTubePlayer from '@site/src/components/YoutubePlayer';
10+
import Label from '@site/src/components/Label';
11+
12+
# Custom widgets
13+
14+
This page demonstrate the custom widgets available in this project.
15+
16+
:::info
17+
All such widgets are stored within `docs/src/components` directory.
18+
:::
19+
20+
## Label - Rounded tags
21+
22+
Widget to add labels such as beta features.
23+
24+
<Tabs>
25+
<TabItem value="code" label="Code">
26+
**Import**
27+
28+
Add import line at the top of the markdown file:
29+
```markdown
30+
import Label from '@site/src/components/Label';
31+
```
32+
33+
**Use**
34+
35+
Place the content to place a Label in your markdown page:
36+
37+
```markdown
38+
<Label value="BETA"/> feature
39+
```
40+
</TabItem>
41+
<TabItem value="preview" label="Preview" default>
42+
<Label value="BETA"/> feature
43+
</TabItem>
44+
</Tabs>
45+
46+
## CenteredImage - Centered image
47+
48+
Widget to center an image on the page.
49+
50+
<Tabs>
51+
<TabItem value="code" label="Code">
52+
**Import**
53+
54+
Add import line at the top of the markdown file:
55+
```markdown
56+
import CenteredImage from '@site/src/components/CenteredImage';
57+
```
58+
59+
**Use**
60+
61+
Place the content to center in your markdown page:
62+
63+
```markdown
64+
<CenteredImage
65+
src="/images/doc/initial_setup_popup.png"
66+
alt="Configuration wizard"
67+
figureNumber={1}
68+
/>
69+
```
70+
</TabItem>
71+
<TabItem value="preview" label="Preview" default>
72+
<CenteredImage
73+
src="/images/doc/initial_setup_popup.png"
74+
alt="Configuration wizard"
75+
figureNumber={1}
76+
/>
77+
</TabItem>
78+
</Tabs>
79+
80+
81+
## Centered - Centered content
82+
83+
Widget to center content within the page.
84+
85+
<Tabs>
86+
<TabItem value="code" label="Code">
87+
**Import**
88+
89+
Add import line at the top of the markdown file:
90+
```markdown
91+
import Centered from '@site/src/components/Centered';
92+
```
93+
94+
**Use**
95+
96+
Place the content to center in your markdown page:
97+
98+
```markdown
99+
<Centered>
100+
Some central text
101+
</Centered>
102+
```
103+
</TabItem>
104+
<TabItem value="preview" label="Preview" default>
105+
<Centered>
106+
Some central text
107+
</Centered>
108+
</TabItem>
109+
</Tabs>
110+
111+
## YoutubePlayer - Embed Youtube videos
112+
113+
Widget to display YouTube videos.
114+
115+
<Tabs>
116+
<TabItem value="code" label="Code">
117+
**Import**
118+
119+
Add import line at the top of the markdown file:
120+
```markdown
121+
import YoutubePlayer from '@site/src/components/YoutubePlayer';
122+
```
123+
124+
**Use**
125+
126+
Place the content to place a Youtube player in your markdown page:
127+
128+
```markdown
129+
<YouTubePlayer
130+
videoId="ko5_FA-TdAU"
131+
author="Cables & Coffee (co-founder)"
132+
description="Quickly see what you can achieve!"
133+
/>
134+
```
135+
</TabItem>
136+
<TabItem value="preview" label="Preview" default>
137+
<YouTubePlayer
138+
videoId="ko5_FA-TdAU"
139+
author="Cables & Coffee (co-founder)"
140+
description="Quickly see what you can achieve!"
141+
/>
142+
</TabItem>
143+
</Tabs>

0 commit comments

Comments
 (0)