Moving docs to the Wiki area
This commit is contained in:
Edward Firmo
@@ -1,137 +1 @@
|
||||
# Add-on: Climate
|
||||
|
||||
## Description
|
||||
This add-on enables the use of your panel's relays to act as a thermostat (either cooler or heater) using the internal temperature sensor and independent of the network availability.
|
||||
|
||||
### Attention
|
||||
1. The NSPanel is limited to 2A per relay. Don't use it for directly power your cooler/heater if exceeding the panel specifications:
|
||||
- 150W/110V/Gang, 300W/110V/Total
|
||||
- 300W/220V/Gang, 600W/220V/Total<br>
|
||||
- More details on the [Sonoff NSPanel's page](https://sonoff.tech/product/central-control-panel/nspanel/) and the [product specifications document](https://sonoff.tech/wp-content/uploads/2021/11/%E4%BA%A7%E5%93%81%E5%8F%82%E6%95%B0%E8%A1%A8-NSPanel-20210831.pdf).
|
||||
|
||||
2. At this moment you have to choose between `heat` or `cool`. The dual/simultaneous operation is not supported at this moment.
|
||||
3. A target temperature must be set on the climate entity in Home Assistant or the page Climate in your panel.
|
||||
|
||||
|
||||
## Installation
|
||||
You will need to add the reference to `addon_climate_heat` or `addon_climate_cool` files on your ESPHome settings in the `package` section and after te `remote_package` (base code), as shown bellow (for `heat` in this example):
|
||||
|
||||
```yaml
|
||||
substitutions:
|
||||
###### CHANGE ME START ######
|
||||
device_name: "YOUR_NSPANEL_NAME"
|
||||
wifi_ssid: !secret wifi_ssid
|
||||
wifi_password: !secret wifi_password
|
||||
|
||||
nextion_update_url: "http://homeassistant.local:8123/local/nspanel_eu.tft"
|
||||
|
||||
##### addon-configuration #####
|
||||
## addon_climate ##
|
||||
heater_relay: "1" # possible values: 1/2
|
||||
|
||||
##### CHANGE ME END #####
|
||||
|
||||
|
||||
packages:
|
||||
remote_package:
|
||||
url: https://github.com/Blackymas/NSPanel_HA_Blueprint
|
||||
ref: main
|
||||
files:
|
||||
- nspanel_esphome.yaml # Core package
|
||||
# - nspanel_esphome_addon_climate_cool.yaml # activate for local climate (cooling) control
|
||||
- nspanel_esphome_addon_climate_heat.yaml # activate for local climate (heater) control
|
||||
|
||||
refresh: 300s
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
The following keys are available to be used in your `substitutions`:
|
||||
|
||||
Key|Required|Supported values|Default|Description
|
||||
:-|:-:|:-:|:-:|:-
|
||||
cooler_relay|Mandatory for `cool`|`1` or `2`|`0` (disabled)|Relay used for control the cooler. User `1` for "Relay 1" or `2` for "Relay 2".
|
||||
heater_relay|Mandatory for `heat`|`1` or `2`|`0` (disabled)|Relay used for control the heater. User `1` for "Relay 1" or `2` for "Relay 2".
|
||||
temp_units|Optional|`°C` or `°F`|`°C`|Temperature unit.
|
||||
min_off_time|Optional|Positive integer representing the number of seconds|`300`|Minimum duration (in seconds) the cooling/heating action must be disengaged before it may be engaged.
|
||||
min_run_time|Optional|Positive integer representing the number of seconds|`300`|Minimum duration (in seconds) the cooling/heating action must be engaged before it may be disengaged.
|
||||
min_idle_time|Optional|Positive integer representing the number of seconds|`30`|Minimum duration (in seconds) the idle action must be active before calling another climate action.
|
||||
temp_min|Optional|Number representing a temperature in the selected unit|`15` for `cool`, `5` for `heat`|The minimum temperature the climate device can reach. Used to set the range of the frontend gauge.
|
||||
temp_max|Optional|Number representing a temperature in the selected unit|`45` for `cool`, `25` for `heat`|The maximum temperature the climate device can reach. Used to set the range of the frontend gauge.
|
||||
temp_step|Optional|Number representing a temperature in the selected unit|`0.5`|The granularity with which the target temperature can be controlled.
|
||||
|
||||
- All values must be delimited with `""`
|
||||
- For more details on the keys, please take a look at [ESPHome Base Climate Configurations](https://esphome.io/components/climate/index.html#base-climate-configuration) and [ESPHome Climate Thermostat - Additional actions behavior](https://esphome.io/components/climate/thermostat.html#additional-actions-behavior).
|
||||
|
||||
|
||||
### Examples:
|
||||
|
||||
#### Cooler:
|
||||
|
||||
```yaml
|
||||
substitutions:
|
||||
###### CHANGE ME START ######
|
||||
device_name: "YOUR_NSPANEL_NAME"
|
||||
wifi_ssid: !secret wifi_ssid
|
||||
wifi_password: !secret wifi_password
|
||||
|
||||
nextion_update_url: "http://homeassistant.local:8123/local/nspanel_us.tft"
|
||||
|
||||
|
||||
##### addon-configuration #####
|
||||
## addon_climate ##
|
||||
cooler_relay: "1" #Use relay 1
|
||||
temp_units: "°F" #Temperatures in Fahrenheit
|
||||
temp_min: "40" #Min supported temperature is 40°F
|
||||
temp_max: "80" #Max supported temperature is 80°F
|
||||
temp_step: "1" #Temperature granularity is 1°F
|
||||
|
||||
##### CHANGE ME END #####
|
||||
|
||||
|
||||
packages:
|
||||
remote_package:
|
||||
url: https://github.com/Blackymas/NSPanel_HA_Blueprint
|
||||
ref: main
|
||||
files:
|
||||
- nspanel_esphome.yaml # Core package
|
||||
- nspanel_esphome_addon_climate_cool.yaml # activate for local climate (cooling) control
|
||||
# - nspanel_esphome_addon_climate_heat.yaml # activate for local climate (heater) control
|
||||
refresh: 300s
|
||||
```
|
||||
|
||||
|
||||
#### Heater:
|
||||
|
||||
```yaml
|
||||
substitutions:
|
||||
###### CHANGE ME START ######
|
||||
device_name: "YOUR_NSPANEL_NAME"
|
||||
wifi_ssid: !secret wifi_ssid
|
||||
wifi_password: !secret wifi_password
|
||||
|
||||
nextion_update_url: "http://homeassistant.local:8123/local/nspanel_us.tft"
|
||||
|
||||
|
||||
##### addon-configuration #####
|
||||
## addon_climate ##
|
||||
heater_relay: "1" #Use relay 1
|
||||
temp_units: "°F" #Temperatures in Fahrenheit
|
||||
temp_min: "40" #Min supported temperature is 40°F
|
||||
temp_max: "80" #Max supported temperature is 80°F
|
||||
temp_step: "1" #Temperature granularity is 1°F
|
||||
|
||||
##### CHANGE ME END #####
|
||||
|
||||
|
||||
packages:
|
||||
remote_package:
|
||||
url: https://github.com/Blackymas/NSPanel_HA_Blueprint
|
||||
ref: main
|
||||
files:
|
||||
- nspanel_esphome.yaml # Core package
|
||||
# - nspanel_esphome_addon_climate_cool.yaml # activate for local climate (cooling) control
|
||||
- nspanel_esphome_addon_climate_heat.yaml # activate for local climate (heater) control
|
||||
refresh: 300s
|
||||
```
|
||||
|
||||
This page was moved to the Wiki area: https://github.com/Blackymas/NSPanel_HA_Blueprint/wiki/(EN)-Add%E2%80%90on:-Climate
|
||||
@@ -1,52 +1 @@
|
||||
# Alarm Control Panel
|
||||
|
||||
You can control an Alarm Control Panel from your NSPanel, which will allow you to set the alarm mode between the standard modes supported by Home Assistant (Home, Away, Night, Vacation or Custom bypass) or disarm the alarm.
|
||||
|
||||
Currently, only alarms without a code or alarms with a numeric code will be supported. If your alarm requires a text code, you will still be able to display it on your NSPanel, however, when you click in any button it will send services calls to Home Assistant without the code and it will fail for the calls where a code is required.
|
||||
|
||||
|
||||
### Security advisory
|
||||
|
||||
By default, the communication between your NSPanel (ESPHome) and Home Assistant (HA) is not encrypted, which means a person with access to your network could potentially monitor the communication between your panel and HA and replicate the service calls. Although this is not a big issue for most of the service calls (turn-on a light, close a curtain, etc.), it can be a problem when controlling your alarm system.<br>
|
||||
Based on that, we hardly reccoment the use of API encryption for all users controlling an Alarm system via a NSPanel. You can easily enable this by following the ["API encryption" example available here](customization.md#api-encryption).
|
||||
|
||||
|
||||
## Configuration
|
||||
### Allow the device to make Home Assistant service calls
|
||||
First, you have to configure your Home Assistant to allow your panel to make service calls. All other services are called from the Blueprint, however this requires the ESPHome to send an event containing in plain text all the information needed to the service call, which could be a security issue, so all the alarm calls will be driven by the panel to ensure a safer environment.<br>
|
||||
To enable this option, go to your ESPHome integrations panel (Settings > Devices and Services > ESPHome) and click "Configure" next to the entry related to your panel:<br>
|
||||
|
||||
|
||||
Then check the option "Allow the device to make Home Assistant service calls":<br>
|
||||
|
||||
<br>
|
||||
### Blueprint settings
|
||||
Open the automation based on the NSPanel Blueprint and look for a section related to "Alarm Control Panel".<br>
|
||||
Select your alarm control panel entity, click "Save", and your are done. :sunglasses:<br>
|
||||
|
||||
|
||||
|
||||
|
||||
## Controlling your alarm from your panel
|
||||
When an alarm control panel is set in your Blueprint automation, you will see the alarm icon on your panel's Home page. This icon will change following the alarm state as described in the table below.
|
||||
|
||||
A click on that icon will show the Alarm Control Panel page:<br>
|
||||
|
||||
|
||||
You can change your alarm settings with a single click on the button related to the new state you want to set your alarm to, or close the page to go back to Home page.
|
||||
|
||||
### Description of states shown with the alarm icon
|
||||
|
||||
State | Color | Icon | Icon name | Description
|
||||
-- | -- | -- | -- | --
|
||||
disarmed | White ||mdi:shield-off-outline | The alarm is disarmed (off).
|
||||
armed_home | Green || mdi:shield-home-outline | The alarm is armed in home mode.
|
||||
armed_away | Green || mdi:shield-lock-outline | The alarm is armed in away mode.
|
||||
armed_night | Green || mdi:shield-moon-outline | The alarm is armed in night mode.
|
||||
armed_vacation | Green || mdi:shield-airplane-outline | The alarm is armed in vacation mode.
|
||||
armed_custom_bypass | Green || mdi:shield-half-full | The alarm is armed in bypass mode.
|
||||
pending | Amber || mdi:shield-outline | The alarm is pending (towards triggered).
|
||||
arming | Amber || mdi:shield-outline | The alarm is arming.
|
||||
disarming | Amber || mdi:shield-off-outline | The alarm is disarming.
|
||||
triggered | Red || mdi:shield-alert-outline | The alarm is triggered.
|
||||
unknown / unavailable | White || mdi:shield-alert-outline | The alarm state is unknown or unavailable
|
||||
This page was moved to the Wiki area: https://github.com/Blackymas/NSPanel_HA_Blueprint/wiki/(EN)-Alarm-Control-Panel
|
||||
@@ -1,300 +1 @@
|
||||
# Customization
|
||||
|
||||
## Description
|
||||
This project adds lots of functionalities to your NSPanel and we are constantly adding new features based on user's feedback. However, you might have some specific case that are not included on the current implementation or is not a common case for other users.
|
||||
|
||||
You can take advantage of [ESPHome Configuration Types](https://esphome.io/guides/configuration-types.html) to add your custom functionality or even to customize an existing functionality with minimum effort and this document intents to clarify how to use this and give some examples of customization.
|
||||
|
||||
Please feel free to add your own customation to this document by creating a PR in the `dev` branch.
|
||||
|
||||
***IMPORTANT:***
|
||||
- *Use customization at your own risk. Custom/advanced systems won't be supported by this project's team.*
|
||||
- *Please monitor the memory consumption when using customizations. Getting closer to the full memory can drive to errors in the system or prevent your system to support the future updates.*
|
||||
|
||||
|
||||
## Instructions
|
||||
There's nothing particular for this project, so you can just use any of the [ESPHome Configuration Types](https://esphome.io/guides/configuration-types.html) and only edit your local ESPHome yaml settings.
|
||||
|
||||
Most of the ESPHome components in this project contains an `Id`, which can be used together with the `!extend` key to add or replace existing code.
|
||||
|
||||
You should add your customizations at the end of your ESPHome yaml, as in the example bellow:
|
||||
|
||||
```yaml
|
||||
substitutions:
|
||||
###### CHANGE ME START ######
|
||||
device_name: "YOUR_NSPANEL_NAME"
|
||||
wifi_ssid: !secret wifi_ssid
|
||||
wifi_password: !secret wifi_password
|
||||
|
||||
nextion_update_url: "http://homeassistant.local:8123/local/nspanel_us.tft"
|
||||
|
||||
##### addon-configuration #####
|
||||
## addon_climate ##
|
||||
# addon_climate_heater_relay: "1" # possible values: 1/2
|
||||
|
||||
##### CHANGE ME END #####
|
||||
|
||||
packages:
|
||||
remote_package:
|
||||
url: https://github.com/Blackymas/NSPanel_HA_Blueprint
|
||||
ref: main
|
||||
files:
|
||||
- nspanel_esphome.yaml # Core package
|
||||
# - nspanel_esphome_addon_climate_cool.yaml # activate for local climate (cooling) control
|
||||
# - nspanel_esphome_addon_climate_heat.yaml # activate for local climate (heater) control
|
||||
refresh: 300s
|
||||
|
||||
##### My customization - Start #####
|
||||
# Encrypt the communication between ESPHome and Home Assistant
|
||||
api:
|
||||
encryption:
|
||||
key: !secret api_encryption_key
|
||||
# More detailed log (for troubleshooting only)
|
||||
logger:
|
||||
level: VERBOSE
|
||||
##### My customization - End #####
|
||||
```
|
||||
|
||||
|
||||
## Examples
|
||||
### API encryption
|
||||
This is highly recommended when you are transfer sensitive information between your panel and Home Assistant, as when you use your panel to enter the PIN for an Alarm Control Panel.
|
||||
|
||||
```yaml
|
||||
# Encrypt the communication between ESPHome and Home Assistant
|
||||
api:
|
||||
encryption:
|
||||
key: !secret api_encryption_key
|
||||
```
|
||||
|
||||
### Custom OTA password
|
||||
By default, the Wi-Fi password will be used as your OTA password, but you can replace it.<br>
|
||||
First, you need to change the default password using this code.
|
||||
```yaml
|
||||
# change OTA password, remove after flashing
|
||||
esphome:
|
||||
on_boot:
|
||||
- lambda: |-
|
||||
id(my_ota).set_auth_password("New password");
|
||||
ota:
|
||||
password: !secret wifi_password
|
||||
id: my_ota
|
||||
```
|
||||
After flashing the device, you must remove the code above and replace it with the code below to start using this customization.
|
||||
```yaml
|
||||
# Use my global OTA password
|
||||
ota:
|
||||
password: !secret ota_password
|
||||
```
|
||||
|
||||
### Web server credentials
|
||||
By default, the web server credentials are defined by this project using `admin` as `username` and your `Wi-Fi password` as `password`, but you can replace it using this customization:
|
||||
```yaml
|
||||
# Custom web server credentials
|
||||
web_server:
|
||||
auth:
|
||||
username: !secret web_server_username
|
||||
password: !secret web_server_password
|
||||
```
|
||||
|
||||
### Reboot when API fails
|
||||
Reboot your panel if it loses it's connection to Home Assistant for more than a certain time (15 minutes in this example).<br>
|
||||
Sometimes the low level ESP functions could report that the ESP is connected to the network, when in fact it is not and only a full reboot fixes it.<br>
|
||||
To support long times without Wi-Fi, this is disabled by default in this project, but you can set a reasonable interval to restart, based on your network reliability.
|
||||
```yaml
|
||||
# Reboot if HA is not connected for 15 minutes
|
||||
api:
|
||||
reboot_timeout: 15min
|
||||
```
|
||||
|
||||
### Change uart's baud rate
|
||||
Use this to change the baud rate on the communication between ESPHome and Nextion display.<br>
|
||||
Important: Use only when troubleshooting as your display should be set to always communicate at 115200 bps.
|
||||
```yaml
|
||||
# Set Nextion comm's baud rate to 9600 bps
|
||||
uart:
|
||||
baud_rate: 9600
|
||||
```
|
||||
|
||||
### Manual IP
|
||||
Set IP address manually.
|
||||
```yaml
|
||||
# Set IP address manually
|
||||
wifi:
|
||||
networks:
|
||||
- id: !extend wifi_default
|
||||
manual_ip:
|
||||
static_ip: 192.168.0.123
|
||||
gateway: 192.168.0.1
|
||||
subnet: 255.255.255.0
|
||||
```
|
||||
|
||||
### Hidden Wi-Fi
|
||||
Connect to a hidden Wi-Fi network.
|
||||
```yaml
|
||||
# Connect to a hidden Wi-Fi network.
|
||||
wifi:
|
||||
networks:
|
||||
- id: !extend wifi_default
|
||||
hidden: true
|
||||
fast_connect: true
|
||||
```
|
||||
|
||||
### Connect to multiple networks
|
||||
NSPanel will attempt to connect to the one with the highest signal strength or, if you set a priority, it will try to connect to the highest priority. After failing it will connect to the second network.
|
||||
```yaml
|
||||
# Set dual network
|
||||
wifi:
|
||||
networks:
|
||||
- id: !extend wifi_default
|
||||
priority: 10
|
||||
- ssid: !secret wifi_ssid_backup
|
||||
password: !secret wifi_password_backup
|
||||
priority: 0
|
||||
```
|
||||
|
||||
### SNTP (time) server
|
||||
ESPHome takes it's time from Home Assistant, however you can configure it to use a Network Time Server instead.
|
||||
```yaml
|
||||
# Use my own local network time server
|
||||
time:
|
||||
- id: !extend time_provider
|
||||
platform: sntp
|
||||
timezone: Europe/Stockholm
|
||||
servers:
|
||||
- !secret mysntpserver
|
||||
- europe.pool.ntp.org
|
||||
- 0.pool.ntp.org
|
||||
```
|
||||
|
||||
|
||||
### Sensor for display awake vs sleeping
|
||||
Creates a binary sensor to indicate either when the display is showing some page (`on`) or sleeping (`off`).
|
||||
```yaml
|
||||
# Is display awake?
|
||||
binary_sensor:
|
||||
- name: ${device_name} Display state
|
||||
id: display_state
|
||||
platform: template
|
||||
lambda: |-
|
||||
return (id(current_page).state != "screensaver");
|
||||
```
|
||||
|
||||
You can easily invert the meaning to have a sensor for display sleeping:
|
||||
```yaml
|
||||
# Is display sleeping?
|
||||
binary_sensor:
|
||||
- name: ${device_name} Display sleeping
|
||||
id: display_sleeping
|
||||
platform: template
|
||||
lambda: |-
|
||||
return (id(current_page).state == "screensaver");
|
||||
```
|
||||
|
||||
|
||||
### Button to upload `nspanel_blank.tft`
|
||||
This can also be used for any other alternative tft file you might want to use frequently:
|
||||
|
||||
```yaml
|
||||
button:
|
||||
##### UPDATE TFT BLANK DISPLAY #####
|
||||
- name: ${device_name} Update TFT display (blank)
|
||||
platform: template
|
||||
icon: mdi:file-sync
|
||||
id: tft_update_blank
|
||||
entity_category: config
|
||||
on_press:
|
||||
- logger.log: "Button pressed: Update TFT display (blank)"
|
||||
- binary_sensor.template.publish:
|
||||
id: nextion_init
|
||||
state: false
|
||||
- delay: 16ms
|
||||
- lambda: |-
|
||||
id(disp1)->set_tft_url("${nextion_update_blank_url}");
|
||||
id(disp1).upload_tft();
|
||||
```
|
||||
You also must add the url for the alternative tft in your substitutions, like this:
|
||||
```yaml
|
||||
nextion_update_blank_url: "http://homeassistant.local:8123/local/nspanel/dev/nspanel_blank.tft"
|
||||
```
|
||||
|
||||
|
||||
### Deep sleep
|
||||
In this example, the panel will deep sleep for 7 hours, starting at 23:00:00 every day, for its maximum energy saving.
|
||||
|
||||
During this time, nothing will be shown, the screen will be off and therefore no response to touch, and the panel will be disconnected from Wi-Fi, but you can still wake-up the panel by pressing one of the hardware buttons (the left one in this example):
|
||||
|
||||
```yaml
|
||||
# Define the wake-up button. Use pin 14 for left button or pin 27 for right button
|
||||
deep_sleep:
|
||||
wakeup_pin: 14
|
||||
wakeup_pin_mode: INVERT_WAKEUP
|
||||
|
||||
time:
|
||||
- id: !extend time_provider
|
||||
on_time:
|
||||
- hours: 23
|
||||
minutes: 0
|
||||
seconds: 0
|
||||
then:
|
||||
- deep_sleep.enter:
|
||||
sleep_duration: 7h
|
||||
```
|
||||
|
||||
You can find more ideas around this on [#955](https://github.com/Blackymas/NSPanel_HA_Blueprint/issues/955).
|
||||
|
||||
|
||||
### Enforce time zone
|
||||
Until v3.4 (including), the time was coming from Home Assistant with it's timezone, so the Blueprint was sending the info with no transformation, to the panel.
|
||||
From v4.0, the time reference still coming from HA (or optionally from a time server), but is calculated in ESPHome, which will try to detect the timezone from the server.
|
||||
|
||||
If your system is not showing the time in the correct timezone, it's probabily ESPHome not succeeding on finding your time zone.
|
||||
You can easily force a timezone by adding this to your ESPHome settings:
|
||||
|
||||
```yaml
|
||||
time:
|
||||
- id: !extend time_provider
|
||||
timezone: "America/Cancun"
|
||||
```
|
||||
|
||||
|
||||
### Compiling ESPHome on lower powered machines
|
||||
For systems with lower CPU or memory capabilities, like an RPi 3 or systems with less than 2GB of RAM, this could help preventing errors caused by lack of resources when compiling ESPHome firmware.
|
||||
|
||||
More datails on the [ESPHome docs](https://esphome.io/changelog/2022.11.0.html#running-esphome-on-lower-powered-machines).
|
||||
```yaml
|
||||
# Limit the amount of resources used for compiling
|
||||
esphome:
|
||||
compile_process_limit: 1
|
||||
```
|
||||
|
||||
|
||||
### Sleep & Wake-up buttons
|
||||
There are several ways to wake-up or put your panel to sleep, but in this example we tried a simple approach by adding two buttons (you can implement only one of those if you want):
|
||||
```yaml
|
||||
button:
|
||||
# Adds a button to put the panel to sleep
|
||||
- name: ${device_name} Sleep
|
||||
id: force_sleep
|
||||
platform: template
|
||||
icon: mdi:sleep
|
||||
on_press:
|
||||
then:
|
||||
- logger.log: Button Sleep pressed
|
||||
- lambda: |-
|
||||
if (id(current_page).state != "screensaver") id(disp1).goto_page("screensaver");
|
||||
|
||||
# Adds a button to wake-up the panel (similar to the existing service)
|
||||
- name: ${device_name} Wake-up
|
||||
id: force_wake_up
|
||||
platform: template
|
||||
icon: mdi:alarm
|
||||
on_press:
|
||||
then:
|
||||
- logger.log: Button Wake-up pressed
|
||||
- lambda: |-
|
||||
if (id(current_page).state == "screensaver") id(disp1).goto_page(id(wakeup_page_name).state.c_str());
|
||||
// id(timer_page).execute(id(wakeup_page_name).state.c_str()); // enable this if you want page timeout to be reset
|
||||
id(timer_sleep).execute(id(wakeup_page_name).state.c_str(), int(id(timeout_sleep).state));
|
||||
id(timer_dim).execute(id(wakeup_page_name).state.c_str(), int(id(timeout_dim).state));
|
||||
```
|
||||
This page was moved to the Wiki area: https://github.com/Blackymas/NSPanel_HA_Blueprint/wiki/(EN)-Customization
|
||||
Reference in New Issue
Block a user