├── .gitignore ├── components └── nspanel_lovelace │ ├── automation.h │ ├── nspanel_lovelace.h │ ├── __init__.py │ ├── nspanel_lovelace.cpp │ └── nspanel_lovelace_upload.cpp ├── examples ├── README.md ├── basic-config.yml └── advanced-config.yml ├── README.md └── LICENSE /.gitignore: -------------------------------------------------------------------------------- 1 | __pycache__/ 2 | *.py[cod] 3 | .history -------------------------------------------------------------------------------- /components/nspanel_lovelace/automation.h: -------------------------------------------------------------------------------- 1 | #pragma once 2 | 3 | #include 4 | 5 | #include "esphome/core/component.h" 6 | #include "esphome/core/automation.h" 7 | #include "nspanel_lovelace.h" 8 | 9 | namespace esphome { 10 | namespace nspanel_lovelace { 11 | 12 | class NSPanelLovelaceMsgIncomingTrigger : public Trigger { 13 | public: 14 | explicit NSPanelLovelaceMsgIncomingTrigger(NSPanelLovelace *parent) { 15 | parent->add_incoming_msg_callback([this](const std::string &value) { this->trigger(value); }); 16 | } 17 | }; 18 | 19 | } // namespace nspanel_lovelace 20 | } // namespace esphome 21 | -------------------------------------------------------------------------------- /examples/README.md: -------------------------------------------------------------------------------- 1 | # ESPHome configuration examples 2 | 3 | ## Basic config 4 | 5 | Minimal configuration with configuration of all peripherals is in [basic-config.yml](basic-config.yml). Buttons are 6 | coupled with respective relays and two Home Assistant serviecs are exposed - `upload_tft` for an explicit upgrade 7 | of the display firmware (can be used for the initial reflash) and `play_rtttl` for playing [RTTTL melodies](https://esphome.io/components/rtttl.html). 8 | 9 | After the NSPanel Lovelace UI firmware is flashed for the first time, the display should show an actionable 10 | notification for upgrade to newer version when NSPanel Lovelace UI Backend is updated from HACS if 11 | the `updateMode` options is set to `auto-notify`, or should be upgraded automatically if it's set to `auto`. 12 | 13 | ## Advanced configuration 14 | 15 | More complex example was contributed by [@spike886](https://github.com/spike886), you can find it in 16 | [advanced-config.yml](advanced-config.yml). 17 | 18 | In this configuration, we expose multiple services to Home Assistant: 19 | 20 | - `upload_tft`: used to upload the firmware to the panel, requires [URL of the firmware](https://docs.nspanel.pky.eu/prepare_nspanel/#flash-firmware-to-nextion-screen) (only the URL) 21 | - `play_rtttl`: play Nokia ringtones on the buzzer of the panel, e.g. `Mario:d=4,o=5,b=100:32p,16e6,16e6,16p,16e6,16p,16c6,16e6,16p,16g6,8p,16p,16g,8p,32p,16c6,8p,16g,8p,16e,8p,16a,16p,16b,16p,16a#,16a,16p,16g,16e6,16g6,16a6,16p,16f6,16g6,16p,16e6,16p,16c6,16d6,16b,p,16g6,16f#6,16f6,16d#6,16p,16e6,16p,16g#,16a,16c6,16p,16a,16c6,16d6,8p,8d#6,16p,16d6,8p,8c6` 22 | - `wake`: wake the screen when it is off 23 | - `show_screensaver`: show the screensaver 24 | - `navigate_to_page`: navigate to the page from the parameter. (The name of the page is created using the type of the card and the key value, like `cardMedia_bedroom`) 25 | - `disable_screensaver`: make sure it won't show screensaver after the timeout (useful for showing something all the time on the screen, like a media card while it's playing) 26 | - `enable_screensaver`: enable the screensaver after it was disabled 27 | - `dim_0_to_100`: dim screen brightness with values from 0 to 100 28 | - `show_entity`: show the card of an entity on the screen. It requires the id of the entity, ex `light.bedroom` and title, ex `Bedroom Light` 29 | - `notify_on_screensaver`: show a notification on the screensaver with 2 lines, it can receive both lines. The notification will disappear when you tap on the screensaver 30 | - `notify_fullscreen`: show a full-screen notification with title description and 2 buttons, and it plays a sound on the buzzer. The buttons are not actionable yet 31 | 32 | This configuration also contains configuration of the `switch` entity that shows how to show the entity 33 | on the display when the light is turned on, and show the screensaver when the light is turned off. 34 | -------------------------------------------------------------------------------- /examples/basic-config.yml: -------------------------------------------------------------------------------- 1 | substitutions: 2 | name: nspanel 3 | device_name: NSPanel 4 | 5 | external_components: 6 | - source: 7 | type: git 8 | url: https://github.com/sairon/esphome-nspanel-lovelace-ui 9 | # Using dev is discouraged, see https://github.com/sairon/esphome-nspanel-lovelace-ui/blob/dev/README.md#usage 10 | ref: dev 11 | components: [nspanel_lovelace] 12 | 13 | esphome: 14 | name: ${name} 15 | 16 | esp32: 17 | board: esp32dev 18 | framework: 19 | type: arduino 20 | 21 | wifi: 22 | ssid: !secret wifi_ssid 23 | password: !secret wifi_password 24 | 25 | nspanel_lovelace: 26 | id: nspanel 27 | 28 | ota: 29 | 30 | logger: 31 | 32 | binary_sensor: 33 | - platform: gpio 34 | name: $device_name Left Button 35 | internal: true 36 | pin: 37 | number: 14 38 | inverted: true 39 | on_click: 40 | - switch.toggle: relay_1 41 | 42 | - platform: gpio 43 | name: $device_name Right Button 44 | internal: true 45 | pin: 46 | number: 27 47 | inverted: true 48 | on_click: 49 | - switch.toggle: relay_2 50 | 51 | sensor: 52 | - platform: wifi_signal 53 | name: $device_name WiFi Signal 54 | update_interval: 60s 55 | internal: true 56 | 57 | - platform: ntc 58 | id: temperature 59 | sensor: resistance_sensor 60 | calibration: 61 | b_constant: 3950 62 | reference_temperature: 25°C 63 | reference_resistance: 10kOhm 64 | name: $device_name Temperature 65 | 66 | - platform: resistance 67 | id: resistance_sensor 68 | sensor: ntc_source 69 | configuration: DOWNSTREAM 70 | resistor: 11.2kOhm 71 | internal: true 72 | 73 | - platform: adc 74 | id: ntc_source 75 | pin: 38 76 | update_interval: 10s 77 | attenuation: 12db 78 | internal: true 79 | 80 | switch: 81 | - platform: gpio 82 | name: $device_name Relay 1 83 | id: relay_1 84 | pin: 85 | number: 22 86 | - platform: gpio 87 | name: $device_name Relay 2 88 | id: relay_2 89 | pin: 90 | number: 19 91 | 92 | - platform: gpio 93 | id: screen_power 94 | entity_category: config 95 | pin: 96 | number: 4 97 | inverted: true 98 | restore_mode: ALWAYS_ON 99 | 100 | output: 101 | - platform: ledc 102 | id: buzzer_out 103 | pin: 104 | number: 21 105 | 106 | rtttl: 107 | id: buzzer 108 | output: buzzer_out 109 | 110 | mqtt: 111 | broker: 192.168.1.1 112 | 113 | uart: 114 | - id: tf_uart 115 | tx_pin: 16 116 | rx_pin: 17 117 | baud_rate: 115200 118 | 119 | api: 120 | services: 121 | - service: upload_tft 122 | variables: 123 | url: string 124 | then: 125 | - lambda: |- 126 | id(nspanel).upload_tft(url); 127 | - service: play_rtttl 128 | variables: 129 | song_str: string 130 | then: 131 | - rtttl.play: 132 | rtttl: !lambda 'return song_str;' 133 | -------------------------------------------------------------------------------- /components/nspanel_lovelace/nspanel_lovelace.h: -------------------------------------------------------------------------------- 1 | #pragma once 2 | 3 | #include 4 | 5 | #include "esphome/components/mqtt/mqtt_client.h" 6 | #include "esphome/components/uart/uart.h" 7 | #include "esphome/components/uart/uart_component_esp_idf.h" 8 | #include "esphome/core/automation.h" 9 | #include "esphome/core/component.h" 10 | #include "esphome/core/defines.h" 11 | 12 | #ifdef USE_ARDUINO 13 | #include 14 | #endif 15 | #ifdef USE_ESP_IDF 16 | #include 17 | #endif 18 | 19 | #ifdef USE_TIME 20 | #include "esphome/components/time/real_time_clock.h" 21 | #endif 22 | 23 | namespace esphome { 24 | namespace nspanel_lovelace { 25 | 26 | class NSPanelLovelace : public Component, public uart::UARTDevice { 27 | public: 28 | void setup() override; 29 | void loop() override; 30 | 31 | void set_mqtt(mqtt::MQTTClientComponent *parent) { mqtt_ = parent; } 32 | void set_recv_topic(const std::string &topic) { recv_topic_ = topic; } 33 | void set_send_topic(const std::string &topic) { send_topic_ = topic; } 34 | void set_berry_driver_version(unsigned int value) { berry_driver_version_ = value; } 35 | void set_missed_updates_workaround(bool value) { use_missed_updates_workaround_ = value; } 36 | void set_update_baud_rate(unsigned int value) { update_baud_rate_ = value; } 37 | 38 | float get_setup_priority() const override { return setup_priority::DATA; } 39 | 40 | void dump_config() override; 41 | 42 | void send_custom_command(const std::string &command); 43 | 44 | void add_incoming_msg_callback(std::function callback); 45 | 46 | void send_nextion_command(const std::string &command); 47 | 48 | /** 49 | * Softreset the Nextion 50 | */ 51 | void soft_reset(); 52 | 53 | void start_reparse_mode(); 54 | 55 | void exit_reparse_mode(); 56 | 57 | /** 58 | * Upload the tft file and softreset the Nextion 59 | */ 60 | void upload_tft(const std::string &url); 61 | 62 | protected: 63 | void set_baud_rate_(int baud_rate); 64 | 65 | static uint16_t crc16(const uint8_t *data, uint16_t len); 66 | 67 | uint16_t recv_ret_string_(std::string &response, uint32_t timeout, bool recv_flag); 68 | 69 | bool process_data_(); 70 | void process_command_(const std::string &message); 71 | 72 | mqtt::MQTTClientComponent *mqtt_; 73 | std::string recv_topic_; 74 | std::string send_topic_; 75 | unsigned int berry_driver_version_; 76 | bool use_missed_updates_workaround_ = true; 77 | unsigned int update_baud_rate_; 78 | 79 | CallbackManager incoming_msg_callback_; 80 | 81 | std::vector buffer_; 82 | 83 | bool is_updating_ = false; 84 | bool reparse_mode_ = false; 85 | 86 | uint8_t *transfer_buffer_{nullptr}; 87 | size_t transfer_buffer_size_; 88 | bool upload_first_chunk_sent_ = false; 89 | 90 | /** 91 | * will request chunk_size chunks from the web server 92 | * and send each to the nextion 93 | * @param int contentLength Total size of the file 94 | * @param uint32_t chunk_size 95 | * @return true if success, false for failure. 96 | */ 97 | int content_length_ = 0; 98 | int tft_size_ = 0; 99 | 100 | #ifdef USE_ARDUINO 101 | void init_upload(HTTPClient *http, const std::string &url); 102 | 103 | int upload_by_chunks_(HTTPClient *http, const std::string &url, int range_start); 104 | #elif defined(USE_ESP_IDF) 105 | void init_upload(const std::string &url); 106 | 107 | int upload_by_chunks_(const std::string &url, int range_start); 108 | #endif 109 | 110 | void upload_end_(); 111 | }; 112 | 113 | 114 | } // namespace nspanel_lovelace 115 | } // namespace esphome 116 | -------------------------------------------------------------------------------- /components/nspanel_lovelace/__init__.py: -------------------------------------------------------------------------------- 1 | from esphome import automation 2 | import esphome.config_validation as cv 3 | import esphome.codegen as cg 4 | from esphome.components import mqtt, uart 5 | from esphome.const import ( 6 | CONF_ID, 7 | CONF_TRIGGER_ID, 8 | ) 9 | from esphome.core import CORE 10 | 11 | AUTO_LOAD = ["text_sensor"] 12 | CODEOWNERS = ["@sairon"] 13 | DEPENDENCIES = ["mqtt", "uart", "wifi", "esp32"] 14 | 15 | nspanel_lovelace_ns = cg.esphome_ns.namespace("nspanel_lovelace") 16 | NSPanelLovelace = nspanel_lovelace_ns.class_("NSPanelLovelace", cg.Component, uart.UARTDevice) 17 | 18 | 19 | NSPanelLovelaceMsgIncomingTrigger = nspanel_lovelace_ns.class_( 20 | "NSPanelLovelaceMsgIncomingTrigger", 21 | automation.Trigger.template(cg.std_string) 22 | ) 23 | 24 | CONF_MQTT_PARENT_ID = "mqtt_parent_id" 25 | CONF_MQTT_RECV_TOPIC = "mqtt_recv_topic" 26 | CONF_MQTT_SEND_TOPIC = "mqtt_send_topic" 27 | CONF_INCOMING_MSG = "on_incoming_msg" 28 | CONF_BERRY_DRIVER_VERSION = "berry_driver_version" 29 | CONF_USE_MISSED_UPDATES_WORKAROUND = "use_missed_updates_workaround" 30 | CONF_UPDATE_BAUD_RATE = "update_baud_rate" 31 | 32 | 33 | def validate_config(config): 34 | if int(config[CONF_BERRY_DRIVER_VERSION]) > 0: 35 | if "CustomSend" not in config[CONF_MQTT_SEND_TOPIC]: 36 | # backend uses topic_send.replace("CustomSend", ...) for GetDriverVersion and FlashNextion 37 | raise cv.Invalid(f"{CONF_MQTT_SEND_TOPIC} must contain \"CustomSend\" for correct backend compatibility.\n" 38 | f"Either change it or set {CONF_BERRY_DRIVER_VERSION} to 0.") 39 | return config 40 | 41 | 42 | CONFIG_SCHEMA = cv.All( 43 | cv.Schema( 44 | { 45 | cv.GenerateID(): cv.declare_id(NSPanelLovelace), 46 | cv.GenerateID(CONF_MQTT_PARENT_ID): cv.use_id(mqtt.MQTTClientComponent), 47 | cv.Optional(CONF_MQTT_RECV_TOPIC, default="tele/nspanel/RESULT"): cv.string, 48 | cv.Optional(CONF_MQTT_SEND_TOPIC, default="cmnd/nspanel/CustomSend"): cv.string, 49 | cv.Optional(CONF_INCOMING_MSG): automation.validate_automation( 50 | cv.Schema( 51 | { 52 | cv.GenerateID(CONF_TRIGGER_ID): cv.declare_id(NSPanelLovelaceMsgIncomingTrigger), 53 | } 54 | ) 55 | ), 56 | cv.Optional(CONF_BERRY_DRIVER_VERSION, default=999): cv.positive_int, 57 | cv.Optional(CONF_USE_MISSED_UPDATES_WORKAROUND, default=True): cv.boolean, 58 | cv.Optional(CONF_UPDATE_BAUD_RATE, default=921600): cv.positive_int, 59 | } 60 | ) 61 | .extend(uart.UART_DEVICE_SCHEMA) 62 | .extend(cv.COMPONENT_SCHEMA), 63 | validate_config 64 | ) 65 | 66 | 67 | async def to_code(config): 68 | var = cg.new_Pvariable(config[CONF_ID]) 69 | await cg.register_component(var, config) 70 | await uart.register_uart_device(var, config) 71 | 72 | mqtt_parent = await cg.get_variable(config[CONF_MQTT_PARENT_ID]) 73 | cg.add(var.set_mqtt(mqtt_parent)) 74 | cg.add(var.set_recv_topic(config[CONF_MQTT_RECV_TOPIC])) 75 | cg.add(var.set_send_topic(config[CONF_MQTT_SEND_TOPIC])) 76 | cg.add(var.set_berry_driver_version(config[CONF_BERRY_DRIVER_VERSION])) 77 | cg.add(var.set_missed_updates_workaround(config[CONF_USE_MISSED_UPDATES_WORKAROUND])) 78 | cg.add(var.set_update_baud_rate(config[CONF_UPDATE_BAUD_RATE])) 79 | 80 | for conf in config.get(CONF_INCOMING_MSG, []): 81 | trigger = cg.new_Pvariable(conf[CONF_TRIGGER_ID], var) 82 | await automation.build_automation(trigger, [(cg.std_string, "x")], conf) 83 | 84 | if CORE.is_esp32 and CORE.using_arduino: 85 | cg.add_library("NetworkClientSecure", None) 86 | cg.add_library("HTTPClient", None) 87 | 88 | cg.add_define("USE_NSPANEL_LOVELACE") 89 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # ESPHome component for NSPanel Lovelace UI 2 | 3 | This repository contains ESPHome component that can be used as an alternative to the official 4 | Tasmota driver provided in [NSPanel Lovelace UI](https://github.com/joBr99/nspanel-lovelace-ui) 5 | repository. It still uses the same AppDaemon backend and TFT driver but the MQTT commands 6 | from the AppDaemon are forwarded to a custom component that translates them to the protocol 7 | used by the display's Nextion firmware, providing the same UX for users that prefer ESPHome 8 | over Tasmota. 9 | 10 | Please note that this code is currently in a very early stage of development, based on code 11 | ~~stolen from~~ based on the abandoned code from joBr99's repo (which is actually based on an 12 | [outstanding PR for the stock NSPanel FW](https://github.com/esphome/esphome/pull/2702)) and 13 | official [ESPHome Nextion component](https://github.com/esphome/esphome/tree/dev/esphome/components/nextion) 14 | (TFT FW upload). Once the code stabilizes (no ETA), properly semver-tagged releases will likely 15 | appear. 16 | 17 | ## Usage 18 | 19 | Add reference to this repository to the `external_components` definitions. Make sure that `ref` is a valid tag 20 | from the [Releases](https://github.com/sairon/esphome-nspanel-lovelace-ui/tags) page (e.g. `v0.3.1`) or an existing 21 | [branch](https://github.com/sairon/esphome-nspanel-lovelace-ui/branches) (e.g. `release/v0.3.x`). 22 | You can use `dev` for the latest bleeding-edge version but be aware that things may break from time to time. 23 | 24 | ```yaml 25 | external_components: 26 | - source: 27 | type: git 28 | url: https://github.com/sairon/esphome-nspanel-lovelace-ui 29 | ref: release/dev 30 | components: [nspanel_lovelace] 31 | ``` 32 | 33 | To handle messages received via MQTT from the AppDaemon, first create the `mqtt` component with the address of your 34 | MQTT broker: 35 | 36 | ```yaml 37 | mqtt: 38 | broker: 192.168.1.1 39 | ``` 40 | 41 | Then initialize the `nspanel_lovelace` component by adding the following line: 42 | 43 | ```yaml 44 | nspanel_lovelace: 45 | ``` 46 | 47 | There are several options you can use: 48 | 49 | - `id`: ID of the component used in lambdas 50 | - `mqtt_recv_topic`: change if you are using different `panelRecvTopic` in your AppDaemon config 51 | - `mqtt_send_topic`: change if you are using different `panelSendTopic` in your AppDaemon config 52 | - `on_incoming_message`: action called when a message is received from the NSPanel firmware (e.g. on a touch event) 53 | - `berry_driver_version`: version of the official Tasmota Berry driver version reported to AppDaemon backend. If set to `0`, automatic updates or notifications about them are effectively disabled. Defaults to `999`. 54 | - `use_missed_updates_workaround`: use workaround for [missed status updates](https://github.com/sairon/esphome-nspanel-lovelace-ui/issues/8) - introduce short delay in internal ESPHome-NSPanel communication. Defaults to `true`, usually there should be no need to disable this option. 55 | - `update_baud_rate`: baud rate to use when updating the TFT firmware, defaults to `921600`. Set to `115200` if you encounter any issues during the updates. 56 | 57 | ### TFT firmware update 58 | 59 | Firmware of the TFT can be updated using the `upload_tft` function - for that you can create a service that can 60 | be triggered from the Home Assistant when needed (make sure you have defined an ID for the NSPanel component): 61 | 62 | ```yaml 63 | api: 64 | - service: upload_tft 65 | variables: 66 | url: string 67 | then: 68 | - lambda: |- 69 | id(nspanel).upload_tft(url); 70 | ``` 71 | 72 | ### Coexistence with Bluetooth components 73 | 74 | There is a [known issue](https://github.com/sairon/esphome-nspanel-lovelace-ui/issues/21) that some operations, 75 | especially the TFT firmware update, can become unreliable when components using Bluetooth are enabled 76 | (like [esp32_ble_tracker](https://esphome.io/components/esp32_ble_tracker.html) or its extension 77 | [bluetooth_proxy](https://esphome.io/components/bluetooth_proxy.html)). Generally it's recommended 78 | to disable the Web Server component and do a re-flash using the serial cable if the device was originally 79 | flashed using ESPHome version older than 2012.12.0. However, this doesn't fix the problem during the TFT update. 80 | A workaround is to stop the Bluetooth scanning before the upgrade is started. To do that, simply add an ID to 81 | the `esp32_ble_tracker` component (it's added implicitly with `bluetooth_proxy`, so if you don't have it in 82 | your configuration, just add it), e.g.: 83 | 84 | ```yaml 85 | esp32_ble_tracker: 86 | id: ble_tracker 87 | ``` 88 | 89 | and then modify the `upload_tft` action to call the `stop_scan` action on it before the upload is started: 90 | 91 | ```yaml 92 | - service: upload_tft 93 | variables: 94 | url: string 95 | then: 96 | - lambda: |- 97 | id(ble_tracker).stop_scan(); 98 | id(nspanel).upload_tft(url); 99 | ``` 100 | 101 | Please note that the upgrade will still fail if it is performed from the on-screen notification about new 102 | firmware version. Unfortunately there is no easy fix for that, in that case it is recommended to avoid 103 | `auto` or `auto-notify` options for the `updateMode` in the backend configuration. 104 | 105 | ### Other functions 106 | 107 | There are currently few more public functions which can be useful for debugging or writing custom automations 108 | for controlling the display: 109 | 110 | - `send_custom_command(command)`: send NSPanel Lovelace UI custom command (`0x55 0xBB` + len prefix, CRC suffix) 111 | - `send_nextion_command(command)`: send Nextion command (suffixed with `0xFF 0xFF 0xFF`) 112 | - `start_reparse_mode()`: start Nextion reparse mode (component will also stop handling data from the display) 113 | - `exit_reparse_mode()`: exit Nextion reparse mode 114 | 115 | ## Example configuration 116 | 117 | See the [examples](examples) folder for configuration examples. 118 | 119 | ## License 120 | 121 | Code in this repository is licensed under the [ESPHome License](LICENSE) (MIT for Python sources, GPL for C++). 122 | -------------------------------------------------------------------------------- /components/nspanel_lovelace/nspanel_lovelace.cpp: -------------------------------------------------------------------------------- 1 | #include 2 | #include "nspanel_lovelace.h" 3 | 4 | #include "esphome/core/application.h" 5 | #include "esphome/core/helpers.h" 6 | #include "esphome/core/util.h" 7 | 8 | namespace esphome { 9 | namespace nspanel_lovelace { 10 | 11 | static const char *const TAG = "nspanel_lovelace"; 12 | 13 | void NSPanelLovelace::setup() { 14 | this->mqtt_->subscribe(this->send_topic_, [this](const std::string &topic, const std::string &payload) { 15 | this->send_custom_command(payload); 16 | // workaround for https://github.com/sairon/esphome-nspanel-lovelace-ui/issues/8 17 | if (this->use_missed_updates_workaround_) delay(75); 18 | }); 19 | 20 | if (this->berry_driver_version_ > 0) { 21 | this->mqtt_->subscribe(std::regex_replace(this->send_topic_, std::regex("CustomSend"), "GetDriverVersion"), 22 | [this](const std::string &topic, const std::string &payload) { 23 | this->mqtt_->publish_json(this->recv_topic_, [this](ArduinoJson::JsonObject root) { 24 | root["nlui_driver_version"] = this->berry_driver_version_; 25 | }); 26 | }); 27 | 28 | this->mqtt_->subscribe(std::regex_replace(this->send_topic_, std::regex("CustomSend"), "FlashNextion"), 29 | [this](const std::string &topic, const std::string &payload) { 30 | ESP_LOGD(TAG, "FlashNextion called with URL '%s'", payload.c_str()); 31 | 32 | // Calling upload_tft in MQTT callback directly would crash ESPHome - using a scheduler 33 | // task avoids that. Maybe there is another way? 34 | App.scheduler.set_timeout( 35 | this, "nspanel_lovelace_flashnextion_upload", 100, [this, payload]() { 36 | ESP_LOGD(TAG, "Starting FlashNextion with URL '%s'", payload.c_str()); 37 | this->upload_tft(payload); 38 | }); 39 | }); 40 | } 41 | } 42 | 43 | void NSPanelLovelace::loop() { 44 | if (this->is_updating_ || this->reparse_mode_) { 45 | return; 46 | } 47 | 48 | uint8_t d; 49 | 50 | while (this->available()) { 51 | this->read_byte(&d); 52 | this->buffer_.push_back(d); 53 | if (!this->process_data_()) { 54 | ESP_LOGW(TAG, "Unparsed data: 0x%02x", d); 55 | this->buffer_.clear(); 56 | } 57 | } 58 | } 59 | 60 | bool NSPanelLovelace::process_data_() { 61 | uint32_t at = this->buffer_.size() - 1; 62 | auto *data = &this->buffer_[0]; 63 | uint8_t new_byte = data[at]; 64 | 65 | // Byte 0: HEADER1 (always 0x55) 66 | if (at == 0) 67 | return new_byte == 0x55; 68 | // Byte 1: HEADER2 (always 0xBB) 69 | if (at == 1) 70 | return new_byte == 0xBB; 71 | 72 | // Byte 3 & 4 - length (little endian) 73 | if (at == 2 || at == 3){ 74 | return true; 75 | } 76 | uint16_t length = encode_uint16(data[3], data[2]); 77 | 78 | // Wait until all data comes in 79 | if (at - 4 < length){ 80 | // ESP_LOGD(TAG, "Message (%d/%d): 0x%02x", at - 3, length, new_byte); 81 | return true; 82 | } 83 | 84 | // Last two bytes: CRC; return after first one 85 | if (at == 4 + length) { 86 | return true; 87 | } 88 | 89 | uint16_t crc16 = encode_uint16(data[4 + length + 1], data[4 + length]); 90 | uint16_t calculated_crc16 = NSPanelLovelace::crc16(data, 4 + length); 91 | 92 | if (crc16 != calculated_crc16) { 93 | ESP_LOGW(TAG, "Received invalid message checksum %02X!=%02X", crc16, calculated_crc16); 94 | return false; 95 | } 96 | 97 | const uint8_t *message_data = data + 4; 98 | std::string message(message_data, message_data + length); 99 | 100 | this->process_command_(message); 101 | this->buffer_.clear(); 102 | return true; 103 | } 104 | 105 | void NSPanelLovelace::process_command_(const std::string &message) { 106 | this->mqtt_->publish_json(this->recv_topic_, [message](ArduinoJson::JsonObject root){ 107 | root["CustomRecv"] = message; 108 | }); 109 | this->incoming_msg_callback_.call(message); 110 | } 111 | 112 | void NSPanelLovelace::add_incoming_msg_callback(std::function callback) { 113 | this->incoming_msg_callback_.add(std::move(callback)); 114 | } 115 | 116 | void NSPanelLovelace::dump_config() { ESP_LOGCONFIG(TAG, "NSPanelLovelace:"); } 117 | 118 | void NSPanelLovelace::send_nextion_command(const std::string &command) { 119 | ESP_LOGD(TAG, "Sending: %s", command.c_str()); 120 | this->write_str(command.c_str()); 121 | const uint8_t to_send[3] = {0xFF, 0xFF, 0xFF}; 122 | this->write_array(to_send, sizeof(to_send)); 123 | } 124 | 125 | void NSPanelLovelace::send_custom_command(const std::string &command) { 126 | if (this->is_updating_) 127 | return; // don't execute custom commands - UI updates could spoil the upload 128 | 129 | ESP_LOGD(TAG, "Sending custom command: %s", command.c_str()); 130 | std::vector data = {0x55, 0xBB}; 131 | data.push_back(command.length() & 0xFF); 132 | data.push_back((command.length() >> 8) & 0xFF); 133 | data.insert(data.end(), command.begin(), command.end()); 134 | auto crc = crc16(data.data(), data.size()); 135 | data.push_back(crc & 0xFF); 136 | data.push_back((crc >> 8) & 0xFF); 137 | this->write_array(data); 138 | } 139 | 140 | void NSPanelLovelace::soft_reset() { this->send_nextion_command("rest"); } 141 | 142 | uint16_t NSPanelLovelace::recv_ret_string_(std::string &response, uint32_t timeout, bool recv_flag) { 143 | uint16_t ret; 144 | uint8_t c = 0; 145 | uint8_t nr_of_ff_bytes = 0; 146 | uint64_t start; 147 | bool exit_flag = false; 148 | bool ff_flag = false; 149 | 150 | start = millis(); 151 | 152 | while ((timeout == 0 && this->available()) || millis() - start <= timeout) { 153 | if (!this->available()) { 154 | App.feed_wdt(); 155 | continue; 156 | } 157 | 158 | this->read_byte(&c); 159 | if (c == 0xFF) { 160 | nr_of_ff_bytes++; 161 | } else { 162 | nr_of_ff_bytes = 0; 163 | ff_flag = false; 164 | } 165 | 166 | if (nr_of_ff_bytes >= 3) 167 | ff_flag = true; 168 | 169 | response += (char) c; 170 | if (recv_flag) { 171 | if (response.find(0x05) != std::string::npos) { 172 | exit_flag = true; 173 | } 174 | } 175 | App.feed_wdt(); 176 | delay(2); 177 | 178 | if (exit_flag || ff_flag) { 179 | break; 180 | } 181 | } 182 | 183 | if (ff_flag) 184 | response = response.substr(0, response.length() - 3); // Remove last 3 0xFF 185 | 186 | ret = response.length(); 187 | return ret; 188 | } 189 | 190 | uint16_t NSPanelLovelace::crc16(const uint8_t *data, uint16_t len) { 191 | uint16_t crc = 0xFFFF; 192 | while (len--) { 193 | 194 | crc ^= *data++; 195 | for (uint8_t i = 0; i < 8; i++) { 196 | if ((crc & 0x01) != 0) { 197 | crc >>= 1; 198 | crc ^= 0xA001; 199 | } else { 200 | crc >>= 1; 201 | } 202 | } 203 | } 204 | return crc; 205 | } 206 | 207 | void NSPanelLovelace::start_reparse_mode() { 208 | this->send_nextion_command("DRAKJHSUYDGBNCJHGJKSHBDN"); 209 | this->send_nextion_command("recmod=0"); 210 | this->send_nextion_command("recmod=0"); 211 | this->send_nextion_command("connect"); 212 | reparse_mode_ = true; 213 | } 214 | 215 | void NSPanelLovelace::exit_reparse_mode() { 216 | this->send_nextion_command("recmod=1"); 217 | reparse_mode_ = false; 218 | } 219 | 220 | void NSPanelLovelace::set_baud_rate_(int baud_rate) { 221 | auto *uart = reinterpret_cast(this->parent_); 222 | uart->set_baud_rate(baud_rate); 223 | uart->setup(); 224 | } 225 | 226 | } // namespace nspanel_lovelace 227 | } // namespace esphome 228 | -------------------------------------------------------------------------------- /examples/advanced-config.yml: -------------------------------------------------------------------------------- 1 | substitutions: 2 | devicename: nspanel-bedroom 3 | friendly_devicename: NSPanel Bedroom 4 | panel_recv_topic: "tele/nspanel/RESULT" 5 | panel_send_topic: "cmnd/nspanel/CustomSend" 6 | 7 | esphome: 8 | name: $devicename 9 | 10 | esp32: 11 | board: esp32dev 12 | 13 | wifi: 14 | networks: 15 | - ssid: !secret wifi_ssid 16 | password: !secret wifi_password 17 | 18 | # Logger. Disable the temperature sensor etc. to focus on the HMI development 19 | logger: 20 | level: DEBUG 21 | logs: 22 | sensor: WARN 23 | resistance: WARN 24 | text_sensor: WARN 25 | ntc: WARN 26 | 27 | ota: 28 | safe_mode: true 29 | 30 | # API. Add api_pwd to your secrets.yaml. 31 | api: 32 | services: 33 | - service: upload_tft 34 | variables: 35 | url: string 36 | then: 37 | - lambda: |- 38 | id(nspanel).upload_tft(url); 39 | # Service to play a rtttl tone 40 | - service: play_rtttl 41 | variables: 42 | song_str: string 43 | then: 44 | - rtttl.play: 45 | rtttl: !lambda "return song_str;" 46 | # Service to send a command directly to the display. Useful for testing 47 | - service: send_command 48 | variables: 49 | cmd: string 50 | then: 51 | - lambda: "id(nspanel).send_custom_command(cmd.c_str());" 52 | # Service to pusblish to mqtt used for refreshin the panel 53 | - service: publish_to_recv_topic 54 | variables: 55 | cmd: string 56 | then: 57 | - mqtt.publish: 58 | topic: $panel_recv_topic 59 | payload: !lambda "return cmd;" 60 | # Service to send a command wake the screen 61 | - service: wake 62 | then: 63 | - lambda: 'id(nspanel).send_custom_command("wake");' 64 | # Service to send a command to show screensaver (some of the values are hardcoded) 65 | - service: show_screensaver 66 | then: 67 | - mqtt.publish: 68 | topic: $panel_recv_topic 69 | payload: '{"CustomRecv":"event,sleepReached,cardGrid"}' 70 | # Service to navigate to screen 71 | - service: navigate_to_page 72 | variables: 73 | page: string 74 | then: 75 | - mqtt.publish_json: 76 | topic: $panel_recv_topic 77 | payload: |- 78 | root["CustomRecv"] = "event,buttonPress2,navigate." + page + ",button"; 79 | # Service to send a command disable screensaver 80 | - service: disable_screensaver 81 | then: 82 | - lambda: 'id(nspanel).send_custom_command("timeout~0");' 83 | # Service to send a command enabled screensaver 84 | - service: enable_screensaver 85 | then: 86 | - lambda: 'id(nspanel).send_custom_command("timeout~20");' 87 | # Service to send a command wake the screen 88 | - service: dim_0_to_100 89 | variables: 90 | intensity: string 91 | then: 92 | - lambda: 'id(nspanel).send_custom_command("dimmode~"+intensity+"~100");' 93 | # Service to send a command To show the screen of a specific like 94 | - service: show_entity 95 | variables: 96 | entity: string 97 | title: string 98 | then: 99 | - lambda: 'id(nspanel).send_custom_command("pageType~popupLight~" + title + "~" + entity);' 100 | # Service to send a command To show the screen of a specific like 101 | - service: notify_on_screensaver 102 | variables: 103 | line1: string 104 | line2: string 105 | then: 106 | - lambda: 'id(nspanel).send_custom_command("notify~" + line1 + "~" + line2);' 107 | - rtttl.play: "short:d=4,o=5,b=100:16e6" 108 | # Service to send a command To show the screen of a specific like 109 | # interaction of the buttons are on implemented yet 110 | - service: notify_fullscreen 111 | variables: 112 | title: string 113 | description: string 114 | button1: string 115 | button2: string 116 | time_secs: string 117 | then: 118 | # show notification screen 119 | - lambda: 'id(nspanel).send_custom_command("pageType~popupNotify");' 120 | # set values on notification screen 121 | # color defined as number created in binary and converted to decimal (rrrrggggbbbbaaaa) 122 | - lambda: 'id(nspanel).send_custom_command("entityUpdateDetail~id~"+ title + "~65535~" + button1 +"~3840~" + button2 + "~61440~" + description + "~65535~" + time_secs);' 123 | - rtttl.play: "scale_up:d=32,o=5,b=100:c,c#,d#,e,f#,g#,a#,b" 124 | 125 | # Uart for the Nextion display 126 | uart: 127 | tx_pin: 16 128 | rx_pin: 17 129 | baud_rate: 115200 130 | 131 | # Functionality for the Nextion display 132 | external_components: 133 | - source: 134 | type: git 135 | url: https://github.com/sairon/esphome-nspanel-lovelace-ui 136 | ref: dev 137 | components: [nspanel_lovelace] 138 | 139 | mqtt: 140 | id: mqtt_client 141 | broker: !secret mqtt_ip 142 | username: !secret mqtt_username 143 | password: !secret mqtt_password 144 | 145 | nspanel_lovelace: 146 | id: nspanel 147 | mqtt_recv_topic: $panel_recv_topic 148 | mqtt_send_topic: $panel_send_topic 149 | 150 | sensor: 151 | # Internal temperature sensor, adc value 152 | - platform: adc 153 | id: ntc_source 154 | pin: 38 155 | update_interval: 10s 156 | attenuation: 12db 157 | 158 | # Internal temperature sensor, adc reading converted to resistance (calculation) 159 | - platform: resistance 160 | id: resistance_sensor 161 | sensor: ntc_source 162 | configuration: DOWNSTREAM 163 | resistor: 11.2kOhm 164 | 165 | # Internal temperature sensor, resistance to temperature (calculation) 166 | - platform: ntc 167 | id: temperature 168 | sensor: resistance_sensor 169 | calibration: 170 | b_constant: 3950 171 | reference_temperature: 25°C 172 | reference_resistance: 10kOhm 173 | name: $friendly_devicename Temperature 174 | 175 | output: 176 | # Buzzer for playing tones 177 | - platform: ledc 178 | id: buzzer_out 179 | pin: 180 | number: 21 181 | 182 | # Rtttl function for buzzer 183 | rtttl: 184 | id: buzzer 185 | output: buzzer_out 186 | 187 | switch: 188 | # Physical relay 1 189 | - platform: gpio 190 | name: $friendly_devicename Relay 1 191 | id: relay_1 192 | pin: 193 | number: 22 194 | on_turn_on: 195 | # show a light on the panel when we swich on the light 196 | # - lambda: 'id(nspanel).send_custom_command("pageType~popupLight~[TITLE TO SHOW ON SCREEN]~[ENTITY NAME]");' 197 | - lambda: 'id(nspanel).send_custom_command("pageType~popupLight~Light 1~light.bed_light");' 198 | on_turn_off: 199 | # send to screensaver when switch off the light 200 | - mqtt.publish: 201 | topic: $panel_recv_topic 202 | payload: '{"CustomRecv":"event,sleepReached,cardGrid"}' 203 | 204 | # Physical relay 2 205 | - platform: gpio 206 | name: $friendly_devicename Relay 2 207 | id: relay_2 208 | pin: 209 | number: 19 210 | on_turn_on: 211 | # show a light on the panel when we swich on the light 212 | - lambda: 'id(nspanel).send_custom_command("pageType~popupLight~Light 2~light.bed_light2");' 213 | on_turn_off: 214 | # send to screensaver when switch off the light 215 | - mqtt.publish: 216 | topic: $panel_recv_topic 217 | payload: '{"CustomRecv":"event,sleepReached,cardGrid"}' 218 | 219 | # Turn screen power on/off. Easy way to configure the screen power control, but this should not be used from HA, as all components must be re-initialized afterwards. For lights, names of lights etc. this practically means that the state must change once to happen. 220 | - platform: gpio 221 | name: Screen Power 222 | id: screen_power 223 | entity_category: config 224 | pin: 225 | number: 4 226 | inverted: true 227 | restore_mode: ALWAYS_ON 228 | 229 | # Binary sensors 230 | binary_sensor: 231 | # Left button below the display 232 | - platform: gpio 233 | name: $friendly_devicename Left Button 234 | pin: 235 | number: GPIO14 236 | inverted: true 237 | id: left_button 238 | on_press: 239 | then: 240 | - switch.turn_on: relay_1 241 | 242 | # Right button below the display 243 | - platform: gpio 244 | name: $friendly_devicename Right Button 245 | pin: 246 | number: GPIO27 247 | inverted: true 248 | id: right_button 249 | on_press: 250 | then: 251 | - switch.toggle: relay_2 252 | -------------------------------------------------------------------------------- /components/nspanel_lovelace/nspanel_lovelace_upload.cpp: -------------------------------------------------------------------------------- 1 | #include "nspanel_lovelace.h" 2 | 3 | #include "esphome/core/application.h" 4 | #include "esphome/core/util.h" 5 | #include "esphome/core/log.h" 6 | #include "esphome/components/network/util.h" 7 | 8 | #include 9 | 10 | namespace esphome { 11 | namespace nspanel_lovelace { 12 | static const char *const TAG = "nspanel_lovelace_upload"; 13 | 14 | // Followed guide 15 | // https://unofficialnextion.com/t/nextion-upload-protocol-v1-2-the-fast-one/1044/2 16 | 17 | #ifdef USE_ARDUINO 18 | int NSPanelLovelace::upload_by_chunks_(HTTPClient *http, const std::string &url, int range_start) { 19 | int range_end; 20 | 21 | if (range_start == 0 && this->transfer_buffer_size_ > 16384) { // Start small at the first run in case of a big skip 22 | range_end = 16384 - 1; 23 | } else { 24 | range_end = range_start + this->transfer_buffer_size_ - 1; 25 | } 26 | 27 | if (range_end > this->tft_size_) 28 | range_end = this->tft_size_; 29 | 30 | char range_header[64]; 31 | sprintf(range_header, "bytes=%d-%d", range_start, range_end); 32 | 33 | ESP_LOGD(TAG, "Requesting range: %s", range_header); 34 | 35 | int tries = 1; 36 | int code; 37 | bool begin_status; 38 | while (tries <= 5) { 39 | begin_status = http->begin(url.c_str()); 40 | 41 | ++tries; 42 | if (!begin_status) { 43 | ESP_LOGD(TAG, "upload_by_chunks_: connection failed"); 44 | continue; 45 | } 46 | 47 | http->addHeader("Range", range_header); 48 | 49 | code = http->GET(); 50 | if (code == 200 || code == 206) { 51 | break; 52 | } 53 | ESP_LOGW(TAG, "HTTP Request failed; URL: %s; Error: %s, retries(%d/5)", url.c_str(), 54 | HTTPClient::errorToString(code).c_str(), tries); 55 | http->end(); 56 | delay(500); // NOLINT 57 | } 58 | 59 | if (tries > 5) { 60 | return -1; 61 | } 62 | 63 | std::string recv_string; 64 | size_t size; 65 | int fetched = 0; 66 | int range = range_end - range_start; 67 | int write_len; 68 | 69 | // fetch next segment from HTTP stream 70 | while (fetched < range) { 71 | size = http->getStreamPtr()->available(); 72 | if (!size) { 73 | App.feed_wdt(); 74 | delay(2); 75 | continue; 76 | } 77 | int c = http->getStreamPtr()->readBytes( 78 | &this->transfer_buffer_[fetched], ((size > this->transfer_buffer_size_) ? this->transfer_buffer_size_ : size)); 79 | fetched += c; 80 | } 81 | http->end(); 82 | ESP_LOGD(TAG, "fetched %d bytes", fetched); 83 | 84 | // upload fetched segments to the display in 4KB chunks 85 | for (int i = 0; i < range; i += 4096) { 86 | App.feed_wdt(); 87 | write_len = this->content_length_ < 4096 ? this->content_length_ : 4096; 88 | this->write_array(&this->transfer_buffer_[i], write_len); 89 | this->content_length_ -= write_len; 90 | ESP_LOGD(TAG, "Uploaded %0.1f %%, remaining %d B", 91 | 100.0 * (this->tft_size_ - this->content_length_) / this->tft_size_, this->content_length_); 92 | 93 | if (!this->upload_first_chunk_sent_) { 94 | this->upload_first_chunk_sent_ = true; 95 | delay(500); // NOLINT 96 | } 97 | 98 | this->recv_ret_string_(recv_string, 5000, true); 99 | if (recv_string[0] != 0x05) { // 0x05 == "ok" 100 | ESP_LOGD(TAG, "recv_string [%s]", 101 | format_hex_pretty(reinterpret_cast(recv_string.data()), recv_string.size()).c_str()); 102 | } 103 | 104 | // handle partial upload request 105 | if (recv_string[0] == 0x08 && recv_string.size() == 5) { 106 | uint32_t result = 0; 107 | for (int j = 0; j < 4; ++j) { 108 | result += static_cast(recv_string[j + 1]) << (8 * j); 109 | } 110 | if (result > 0) { 111 | ESP_LOGD(TAG, "Nextion reported new range %d", result); 112 | this->content_length_ = this->tft_size_ - result; 113 | return result; 114 | } 115 | } 116 | 117 | recv_string.clear(); 118 | } 119 | return range_end + 1; 120 | } 121 | #else 122 | int NSPanelLovelace::upload_by_chunks_(const std::string &url, int range_start) { 123 | ESP_LOGVV(TAG, "url: %s", url.c_str()); 124 | uint range_size = this->tft_size_ - range_start; 125 | ESP_LOGVV(TAG, "tft_size_: %i", this->tft_size_); 126 | ESP_LOGV(TAG, "Available heap: %u", esp_get_free_heap_size()); 127 | int range_end = (range_start == 0) ? std::min(this->tft_size_, 16383) : this->tft_size_; 128 | if (range_size <= 0 or range_end <= range_start) { 129 | ESP_LOGE(TAG, "Invalid range"); 130 | ESP_LOGD(TAG, "Range start: %i", range_start); 131 | ESP_LOGD(TAG, "Range end: %i", range_end); 132 | ESP_LOGD(TAG, "Range size: %i", range_size); 133 | return -1; 134 | } 135 | 136 | esp_http_client_config_t config = { 137 | .url = url.c_str(), 138 | .cert_pem = nullptr, 139 | }; 140 | esp_http_client_handle_t client = esp_http_client_init(&config); 141 | 142 | char range_header[64]; 143 | sprintf(range_header, "bytes=%d-%d", range_start, range_end); 144 | ESP_LOGV(TAG, "Requesting range: %s", range_header); 145 | esp_http_client_set_header(client, "Range", range_header); 146 | ESP_LOGVV(TAG, "Available heap: %u", esp_get_free_heap_size()); 147 | 148 | ESP_LOGV(TAG, "Opening http connetion"); 149 | esp_err_t err; 150 | if ((err = esp_http_client_open(client, 0)) != ESP_OK) { 151 | ESP_LOGE(TAG, "Failed to open HTTP connection: %s", esp_err_to_name(err)); 152 | esp_http_client_cleanup(client); 153 | return -1; 154 | } 155 | 156 | ESP_LOGV(TAG, "Fetch content length"); 157 | int content_length = esp_http_client_fetch_headers(client); 158 | ESP_LOGV(TAG, "content_length = %d", content_length); 159 | if (content_length <= 0) { 160 | ESP_LOGE(TAG, "Failed to get content length: %d", content_length); 161 | esp_http_client_cleanup(client); 162 | return -1; 163 | } 164 | 165 | ESP_LOGV(TAG, "Allocate buffer"); 166 | uint8_t *buffer = new uint8_t[4096]; 167 | std::string recv_string; 168 | if (buffer == nullptr) { 169 | ESP_LOGE(TAG, "Failed to allocate memory for buffer"); 170 | ESP_LOGV(TAG, "Available heap: %u", esp_get_free_heap_size()); 171 | } else { 172 | ESP_LOGV(TAG, "Memory for buffer allocated successfully"); 173 | 174 | while (true) { 175 | App.feed_wdt(); 176 | ESP_LOGVV(TAG, "Available heap: %u", esp_get_free_heap_size()); 177 | int read_len = esp_http_client_read(client, reinterpret_cast(buffer), 4096); 178 | ESP_LOGVV(TAG, "Read %d bytes from HTTP client, writing to UART", read_len); 179 | if (read_len > 0) { 180 | this->write_array(buffer, read_len); 181 | ESP_LOGVV(TAG, "Write to UART successful"); 182 | this->recv_ret_string_(recv_string, 5000, true); 183 | this->content_length_ -= read_len; 184 | ESP_LOGD(TAG, "Uploaded %0.2f %%, remaining %d bytes", 185 | 100.0 * (this->tft_size_ - this->content_length_) / this->tft_size_, this->content_length_); 186 | if (recv_string[0] != 0x05) { // 0x05 == "ok" 187 | ESP_LOGD( 188 | TAG, "recv_string [%s]", 189 | format_hex_pretty(reinterpret_cast(recv_string.data()), recv_string.size()).c_str()); 190 | } 191 | // handle partial upload request 192 | if (recv_string[0] == 0x08 && recv_string.size() == 5) { 193 | uint32_t result = 0; 194 | for (int j = 0; j < 4; ++j) { 195 | result += static_cast(recv_string[j + 1]) << (8 * j); 196 | } 197 | if (result > 0) { 198 | ESP_LOGI(TAG, "Nextion reported new range %" PRIu32, result); 199 | this->content_length_ = this->tft_size_ - result; 200 | // Deallocate the buffer when done 201 | delete[] buffer; 202 | ESP_LOGVV(TAG, "Memory for buffer deallocated"); 203 | esp_http_client_cleanup(client); 204 | esp_http_client_close(client); 205 | return result; 206 | } 207 | } 208 | recv_string.clear(); 209 | } else if (read_len == 0) { 210 | ESP_LOGV(TAG, "End of HTTP response reached"); 211 | break; // Exit the loop if there is no more data to read 212 | } else { 213 | ESP_LOGE(TAG, "Failed to read from HTTP client, error code: %d", read_len); 214 | break; // Exit the loop on error 215 | } 216 | } 217 | 218 | // Deallocate the buffer when done 219 | delete[] buffer; 220 | ESP_LOGVV(TAG, "Memory for buffer deallocated"); 221 | } 222 | esp_http_client_cleanup(client); 223 | esp_http_client_close(client); 224 | return range_end + 1; 225 | } 226 | #endif 227 | 228 | #ifdef USE_ARDUINO 229 | void NSPanelLovelace::init_upload(HTTPClient *http, const std::string &url) { 230 | http->setTimeout(15000); // Yes 15 seconds.... Helps 8266s along 231 | http->setFollowRedirects(HTTPC_STRICT_FOLLOW_REDIRECTS); 232 | bool begin_status = http->begin(url.c_str()); 233 | 234 | if (!begin_status) { 235 | this->is_updating_ = false; 236 | ESP_LOGD(TAG, "connection failed"); 237 | ExternalRAMAllocator allocator(ExternalRAMAllocator::ALLOW_FAILURE); 238 | allocator.deallocate(this->transfer_buffer_, this->transfer_buffer_size_); 239 | return; 240 | } else { 241 | ESP_LOGD(TAG, "Connected"); 242 | } 243 | 244 | http->addHeader("Range", "bytes=0-255"); 245 | const char *header_names[] = {"Content-Range"}; 246 | http->collectHeaders(header_names, 1); 247 | ESP_LOGD(TAG, "Requesting URL: %s", url.c_str()); 248 | 249 | http->setReuse(true); 250 | // try up to 5 times. DNS sometimes needs a second try or so 251 | int tries = 1; 252 | int code = http->GET(); 253 | delay(100); // NOLINT 254 | 255 | while (code != 200 && code != 206 && tries <= 5) { 256 | ESP_LOGW(TAG, "HTTP Request failed; URL: %s; Error: %s, retrying (%d/5)", url.c_str(), 257 | HTTPClient::errorToString(code).c_str(), tries); 258 | 259 | delay(250); // NOLINT 260 | code = http->GET(); 261 | ++tries; 262 | } 263 | 264 | if ((code != 200 && code != 206) || tries > 5) { 265 | this->upload_end_(); 266 | } 267 | 268 | String content_range_string = http->header("Content-Range"); 269 | content_range_string.remove(0, 12); 270 | this->content_length_ = content_range_string.toInt(); 271 | this->tft_size_ = content_length_; 272 | http->end(); 273 | } 274 | #elif defined(USE_ESP_IDF) 275 | void NSPanelLovelace::init_upload(const std::string &url) { 276 | // Define the configuration for the HTTP client 277 | ESP_LOGV(TAG, "Establishing connection to HTTP server"); 278 | ESP_LOGVV(TAG, "Available heap: %u", esp_get_free_heap_size()); 279 | esp_http_client_config_t config = { 280 | .url = url.c_str(), 281 | .cert_pem = nullptr, 282 | .method = HTTP_METHOD_HEAD, 283 | .timeout_ms = 15000, 284 | }; 285 | 286 | // Initialize the HTTP client with the configuration 287 | ESP_LOGV(TAG, "Initializing HTTP client"); 288 | ESP_LOGV(TAG, "Available heap: %u", esp_get_free_heap_size()); 289 | esp_http_client_handle_t http = esp_http_client_init(&config); 290 | if (!http) { 291 | ESP_LOGE(TAG, "Failed to initialize HTTP client."); 292 | return this->upload_end_(); 293 | } 294 | 295 | // Perform the HTTP request 296 | ESP_LOGV(TAG, "Check if the client could connect"); 297 | ESP_LOGV(TAG, "Available heap: %u", esp_get_free_heap_size()); 298 | esp_err_t err = esp_http_client_perform(http); 299 | if (err != ESP_OK) { 300 | ESP_LOGE(TAG, "HTTP request failed: %s", esp_err_to_name(err)); 301 | esp_http_client_cleanup(http); 302 | return this->upload_end_(); 303 | } 304 | 305 | // Check the HTTP Status Code 306 | int status_code = esp_http_client_get_status_code(http); 307 | ESP_LOGV(TAG, "HTTP Status Code: %d", status_code); 308 | size_t tft_file_size = esp_http_client_get_content_length(http); 309 | ESP_LOGD(TAG, "TFT file size: %zu", tft_file_size); 310 | 311 | if (tft_file_size < 4096) { 312 | ESP_LOGE(TAG, "File size check failed. Size: %zu", tft_file_size); 313 | esp_http_client_cleanup(http); 314 | return this->upload_end_(); 315 | } else { 316 | ESP_LOGV(TAG, "File size check passed. Proceeding..."); 317 | } 318 | this->content_length_ = tft_file_size; 319 | this->tft_size_ = tft_file_size; 320 | } 321 | #endif 322 | 323 | void NSPanelLovelace::upload_tft(const std::string &url) { 324 | if (this->is_updating_) { 325 | ESP_LOGD(TAG, "Currently updating"); 326 | return; 327 | } 328 | 329 | if (!network::is_connected()) { 330 | ESP_LOGD(TAG, "network is not connected"); 331 | return; 332 | } 333 | 334 | if (!this->reparse_mode_) { 335 | this->start_reparse_mode(); 336 | } 337 | 338 | this->is_updating_ = true; 339 | 340 | #ifdef USE_ARDUINO 341 | HTTPClient http; 342 | this->init_upload(&http, url); 343 | #elif defined(USE_ESP_IDF) 344 | this->init_upload(url); 345 | #endif 346 | 347 | if (this->content_length_ < 4096) { 348 | ESP_LOGE(TAG, "Failed to get file size"); 349 | this->upload_end_(); 350 | } 351 | 352 | ESP_LOGD(TAG, "Updating Nextion"); 353 | // The Nextion will ignore the update command if it is sleeping 354 | 355 | char command[128]; 356 | // Tells the Nextion the content length of the tft file and baud rate it will be sent at 357 | // Once the Nextion accepts the command it will wait until the file is successfully uploaded 358 | // If it fails for any reason a power cycle of the display will be needed 359 | sprintf(command, "whmi-wris %d,%d,1", this->content_length_, this->update_baud_rate_); 360 | 361 | // Clear serial receive buffer 362 | uint8_t d; 363 | while (this->available()) { 364 | this->read_byte(&d); 365 | }; 366 | 367 | this->send_nextion_command(command); 368 | 369 | // Since 115200 is default and the communication wouldn't work even if it was overridden 370 | // in the uart component initialization, it should be safe to ignore setting the baud rate 371 | // if it's set to 115200. It helps to avoid additional unnecessary HardwareSerial re-init. 372 | if (this->update_baud_rate_ != 115200) { 373 | this->set_baud_rate_(this->update_baud_rate_); 374 | } 375 | 376 | std::string response; 377 | ESP_LOGD(TAG, "Waiting for upgrade response"); 378 | this->recv_ret_string_(response, 2000, true); // This can take some time to return 379 | 380 | // The Nextion display will, if it's ready to accept data, send a 0x05 byte. 381 | ESP_LOGD(TAG, "Upgrade response is [%s]", 382 | format_hex_pretty(reinterpret_cast(response.data()), response.size()).c_str()); 383 | 384 | if (response.find(0x05) != std::string::npos) { 385 | ESP_LOGD(TAG, "preparation for tft update done"); 386 | } else { 387 | ESP_LOGD(TAG, "preparation for tft update failed %d \"%s\"", response[0], response.c_str()); 388 | this->upload_end_(); 389 | } 390 | 391 | // Nextion wants 4096 bytes at a time. Make chunk_size a multiple of 4096 392 | uint32_t chunk_size = 8192; 393 | if (esp_get_free_heap_size() > 40960) { // 32K to keep on hand 394 | chunk_size = esp_get_free_heap_size() - 32768; 395 | chunk_size = chunk_size > 65536 ? 65536 : chunk_size; 396 | } else if (esp_get_free_heap_size() < 10240) { 397 | chunk_size = 4096; 398 | } 399 | 400 | 401 | if (this->transfer_buffer_ == nullptr) { 402 | ExternalRAMAllocator allocator(ExternalRAMAllocator::ALLOW_FAILURE); 403 | // NOLINTNEXTLINE(readability-static-accessed-through-instance) 404 | ESP_LOGD(TAG, "Allocating buffer size %d, Heap size is %u", chunk_size, esp_get_free_heap_size()); 405 | this->transfer_buffer_ = allocator.allocate(chunk_size); 406 | if (this->transfer_buffer_ == nullptr) { // Try a smaller size 407 | ESP_LOGD(TAG, "Could not allocate buffer size: %d trying 4096 instead", chunk_size); 408 | chunk_size = 4096; 409 | ESP_LOGD(TAG, "Allocating %d buffer", chunk_size); 410 | this->transfer_buffer_ = allocator.allocate(chunk_size); 411 | 412 | if (!this->transfer_buffer_) 413 | this->upload_end_(); 414 | } 415 | 416 | this->transfer_buffer_size_ = chunk_size; 417 | } 418 | 419 | // NOLINTNEXTLINE(readability-static-accessed-through-instance) 420 | ESP_LOGD(TAG, "Updating tft from \"%s\" with a file size of %d using %zu chunksize, Heap Size %d", 421 | url.c_str(), this->content_length_, this->transfer_buffer_size_, esp_get_free_heap_size()); 422 | 423 | int result = 0; 424 | while (this->content_length_ > 0) { 425 | #ifdef USE_ARDUINO 426 | result = this->upload_by_chunks_(&http, url, result); 427 | #elif defined(USE_ESP_IDF) 428 | result = this->upload_by_chunks_(url, result); 429 | #endif 430 | if (result < 0) { 431 | ESP_LOGD(TAG, "Error updating Nextion!"); 432 | this->upload_end_(); 433 | } 434 | App.feed_wdt(); 435 | // NOLINTNEXTLINE(readability-static-accessed-through-instance) 436 | ESP_LOGD(TAG, "Heap Size %d, Bytes left %d", esp_get_free_heap_size(), this->content_length_); 437 | } 438 | ESP_LOGD(TAG, "Successfully updated Nextion!"); 439 | 440 | this->upload_end_(); 441 | } 442 | 443 | void NSPanelLovelace::upload_end_() { 444 | ESP_LOGD(TAG, "Restarting Nextion"); 445 | this->soft_reset(); 446 | delay(1500); // NOLINT 447 | ESP_LOGD(TAG, "Restarting esphome"); 448 | esp_restart(); 449 | } 450 | } // namespace nspanel_lovelace 451 | } // namespace esphome 452 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | # ESPHome License 2 | 3 | Copyright (c) 2019 ESPHome 4 | 5 | The ESPHome License is made up of two base licenses: MIT and the GNU GENERAL PUBLIC LICENSE. 6 | The C++/runtime codebase of the ESPHome project (file extensions .c, .cpp, .h, .hpp, .tcc, .ino) are 7 | published under the GPLv3 license. The python codebase and all other parts of this codebase are 8 | published under the MIT license. 9 | 10 | Both MIT and GPLv3 licenses are attached to this document. 11 | 12 | ## MIT License 13 | 14 | Copyright (c) 2019 ESPHome 15 | 16 | Permission is hereby granted, free of charge, to any person obtaining a copy 17 | of this software and associated documentation files (the "Software"), to deal 18 | in the Software without restriction, including without limitation the rights 19 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 20 | copies of the Software, and to permit persons to whom the Software is 21 | furnished to do so, subject to the following conditions: 22 | 23 | The above copyright notice and this permission notice shall be included in all 24 | copies or substantial portions of the Software. 25 | 26 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 27 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 28 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 29 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 30 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 31 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 32 | SOFTWARE. 33 | 34 | ## GPLv3 License 35 | 36 | GNU GENERAL PUBLIC LICENSE 37 | Version 3, 29 June 2007 38 | 39 | Copyright (C) 2007 Free Software Foundation, Inc. 40 | Everyone is permitted to copy and distribute verbatim copies 41 | of this license document, but changing it is not allowed. 42 | 43 | Preamble 44 | 45 | The GNU General Public License is a free, copyleft license for 46 | software and other kinds of works. 47 | 48 | The licenses for most software and other practical works are designed 49 | to take away your freedom to share and change the works. By contrast, 50 | the GNU General Public License is intended to guarantee your freedom to 51 | share and change all versions of a program--to make sure it remains free 52 | software for all its users. We, the Free Software Foundation, use the 53 | GNU General Public License for most of our software; it applies also to 54 | any other work released this way by its authors. You can apply it to 55 | your programs, too. 56 | 57 | When we speak of free software, we are referring to freedom, not 58 | price. Our General Public Licenses are designed to make sure that you 59 | have the freedom to distribute copies of free software (and charge for 60 | them if you wish), that you receive source code or can get it if you 61 | want it, that you can change the software or use pieces of it in new 62 | free programs, and that you know you can do these things. 63 | 64 | To protect your rights, we need to prevent others from denying you 65 | these rights or asking you to surrender the rights. Therefore, you have 66 | certain responsibilities if you distribute copies of the software, or if 67 | you modify it: responsibilities to respect the freedom of others. 68 | 69 | For example, if you distribute copies of such a program, whether 70 | gratis or for a fee, you must pass on to the recipients the same 71 | freedoms that you received. You must make sure that they, too, receive 72 | or can get the source code. And you must show them these terms so they 73 | know their rights. 74 | 75 | Developers that use the GNU GPL protect your rights with two steps: 76 | (1) assert copyright on the software, and (2) offer you this License 77 | giving you legal permission to copy, distribute and/or modify it. 78 | 79 | For the developers' and authors' protection, the GPL clearly explains 80 | that there is no warranty for this free software. For both users' and 81 | authors' sake, the GPL requires that modified versions be marked as 82 | changed, so that their problems will not be attributed erroneously to 83 | authors of previous versions. 84 | 85 | Some devices are designed to deny users access to install or run 86 | modified versions of the software inside them, although the manufacturer 87 | can do so. This is fundamentally incompatible with the aim of 88 | protecting users' freedom to change the software. The systematic 89 | pattern of such abuse occurs in the area of products for individuals to 90 | use, which is precisely where it is most unacceptable. Therefore, we 91 | have designed this version of the GPL to prohibit the practice for those 92 | products. If such problems arise substantially in other domains, we 93 | stand ready to extend this provision to those domains in future versions 94 | of the GPL, as needed to protect the freedom of users. 95 | 96 | Finally, every program is threatened constantly by software patents. 97 | States should not allow patents to restrict development and use of 98 | software on general-purpose computers, but in those that do, we wish to 99 | avoid the special danger that patents applied to a free program could 100 | make it effectively proprietary. To prevent this, the GPL assures that 101 | patents cannot be used to render the program non-free. 102 | 103 | The precise terms and conditions for copying, distribution and 104 | modification follow. 105 | 106 | TERMS AND CONDITIONS 107 | 108 | 0. Definitions. 109 | 110 | "This License" refers to version 3 of the GNU General Public License. 111 | 112 | "Copyright" also means copyright-like laws that apply to other kinds of 113 | works, such as semiconductor masks. 114 | 115 | "The Program" refers to any copyrightable work licensed under this 116 | License. Each licensee is addressed as "you". "Licensees" and 117 | "recipients" may be individuals or organizations. 118 | 119 | To "modify" a work means to copy from or adapt all or part of the work 120 | in a fashion requiring copyright permission, other than the making of an 121 | exact copy. The resulting work is called a "modified version" of the 122 | earlier work or a work "based on" the earlier work. 123 | 124 | A "covered work" means either the unmodified Program or a work based 125 | on the Program. 126 | 127 | To "propagate" a work means to do anything with it that, without 128 | permission, would make you directly or secondarily liable for 129 | infringement under applicable copyright law, except executing it on a 130 | computer or modifying a private copy. Propagation includes copying, 131 | distribution (with or without modification), making available to the 132 | public, and in some countries other activities as well. 133 | 134 | To "convey" a work means any kind of propagation that enables other 135 | parties to make or receive copies. Mere interaction with a user through 136 | a computer network, with no transfer of a copy, is not conveying. 137 | 138 | An interactive user interface displays "Appropriate Legal Notices" 139 | to the extent that it includes a convenient and prominently visible 140 | feature that (1) displays an appropriate copyright notice, and (2) 141 | tells the user that there is no warranty for the work (except to the 142 | extent that warranties are provided), that licensees may convey the 143 | work under this License, and how to view a copy of this License. If 144 | the interface presents a list of user commands or options, such as a 145 | menu, a prominent item in the list meets this criterion. 146 | 147 | 1. Source Code. 148 | 149 | The "source code" for a work means the preferred form of the work 150 | for making modifications to it. "Object code" means any non-source 151 | form of a work. 152 | 153 | A "Standard Interface" means an interface that either is an official 154 | standard defined by a recognized standards body, or, in the case of 155 | interfaces specified for a particular programming language, one that 156 | is widely used among developers working in that language. 157 | 158 | The "System Libraries" of an executable work include anything, other 159 | than the work as a whole, that (a) is included in the normal form of 160 | packaging a Major Component, but which is not part of that Major 161 | Component, and (b) serves only to enable use of the work with that 162 | Major Component, or to implement a Standard Interface for which an 163 | implementation is available to the public in source code form. A 164 | "Major Component", in this context, means a major essential component 165 | (kernel, window system, and so on) of the specific operating system 166 | (if any) on which the executable work runs, or a compiler used to 167 | produce the work, or an object code interpreter used to run it. 168 | 169 | The "Corresponding Source" for a work in object code form means all 170 | the source code needed to generate, install, and (for an executable 171 | work) run the object code and to modify the work, including scripts to 172 | control those activities. However, it does not include the work's 173 | System Libraries, or general-purpose tools or generally available free 174 | programs which are used unmodified in performing those activities but 175 | which are not part of the work. For example, Corresponding Source 176 | includes interface definition files associated with source files for 177 | the work, and the source code for shared libraries and dynamically 178 | linked subprograms that the work is specifically designed to require, 179 | such as by intimate data communication or control flow between those 180 | subprograms and other parts of the work. 181 | 182 | The Corresponding Source need not include anything that users 183 | can regenerate automatically from other parts of the Corresponding 184 | Source. 185 | 186 | The Corresponding Source for a work in source code form is that 187 | same work. 188 | 189 | 2. Basic Permissions. 190 | 191 | All rights granted under this License are granted for the term of 192 | copyright on the Program, and are irrevocable provided the stated 193 | conditions are met. This License explicitly affirms your unlimited 194 | permission to run the unmodified Program. The output from running a 195 | covered work is covered by this License only if the output, given its 196 | content, constitutes a covered work. This License acknowledges your 197 | rights of fair use or other equivalent, as provided by copyright law. 198 | 199 | You may make, run and propagate covered works that you do not 200 | convey, without conditions so long as your license otherwise remains 201 | in force. You may convey covered works to others for the sole purpose 202 | of having them make modifications exclusively for you, or provide you 203 | with facilities for running those works, provided that you comply with 204 | the terms of this License in conveying all material for which you do 205 | not control copyright. Those thus making or running the covered works 206 | for you must do so exclusively on your behalf, under your direction 207 | and control, on terms that prohibit them from making any copies of 208 | your copyrighted material outside their relationship with you. 209 | 210 | Conveying under any other circumstances is permitted solely under 211 | the conditions stated below. Sublicensing is not allowed; section 10 212 | makes it unnecessary. 213 | 214 | 3. Protecting Users' Legal Rights From Anti-Circumvention Law. 215 | 216 | No covered work shall be deemed part of an effective technological 217 | measure under any applicable law fulfilling obligations under article 218 | 11 of the WIPO copyright treaty adopted on 20 December 1996, or 219 | similar laws prohibiting or restricting circumvention of such 220 | measures. 221 | 222 | When you convey a covered work, you waive any legal power to forbid 223 | circumvention of technological measures to the extent such circumvention 224 | is effected by exercising rights under this License with respect to 225 | the covered work, and you disclaim any intention to limit operation or 226 | modification of the work as a means of enforcing, against the work's 227 | users, your or third parties' legal rights to forbid circumvention of 228 | technological measures. 229 | 230 | 4. Conveying Verbatim Copies. 231 | 232 | You may convey verbatim copies of the Program's source code as you 233 | receive it, in any medium, provided that you conspicuously and 234 | appropriately publish on each copy an appropriate copyright notice; 235 | keep intact all notices stating that this License and any 236 | non-permissive terms added in accord with section 7 apply to the code; 237 | keep intact all notices of the absence of any warranty; and give all 238 | recipients a copy of this License along with the Program. 239 | 240 | You may charge any price or no price for each copy that you convey, 241 | and you may offer support or warranty protection for a fee. 242 | 243 | 5. Conveying Modified Source Versions. 244 | 245 | You may convey a work based on the Program, or the modifications to 246 | produce it from the Program, in the form of source code under the 247 | terms of section 4, provided that you also meet all of these conditions: 248 | 249 | a) The work must carry prominent notices stating that you modified 250 | it, and giving a relevant date. 251 | 252 | b) The work must carry prominent notices stating that it is 253 | released under this License and any conditions added under section 254 | 7. This requirement modifies the requirement in section 4 to 255 | "keep intact all notices". 256 | 257 | c) You must license the entire work, as a whole, under this 258 | License to anyone who comes into possession of a copy. This 259 | License will therefore apply, along with any applicable section 7 260 | additional terms, to the whole of the work, and all its parts, 261 | regardless of how they are packaged. This License gives no 262 | permission to license the work in any other way, but it does not 263 | invalidate such permission if you have separately received it. 264 | 265 | d) If the work has interactive user interfaces, each must display 266 | Appropriate Legal Notices; however, if the Program has interactive 267 | interfaces that do not display Appropriate Legal Notices, your 268 | work need not make them do so. 269 | 270 | A compilation of a covered work with other separate and independent 271 | works, which are not by their nature extensions of the covered work, 272 | and which are not combined with it such as to form a larger program, 273 | in or on a volume of a storage or distribution medium, is called an 274 | "aggregate" if the compilation and its resulting copyright are not 275 | used to limit the access or legal rights of the compilation's users 276 | beyond what the individual works permit. Inclusion of a covered work 277 | in an aggregate does not cause this License to apply to the other 278 | parts of the aggregate. 279 | 280 | 6. Conveying Non-Source Forms. 281 | 282 | You may convey a covered work in object code form under the terms 283 | of sections 4 and 5, provided that you also convey the 284 | machine-readable Corresponding Source under the terms of this License, 285 | in one of these ways: 286 | 287 | a) Convey the object code in, or embodied in, a physical product 288 | (including a physical distribution medium), accompanied by the 289 | Corresponding Source fixed on a durable physical medium 290 | customarily used for software interchange. 291 | 292 | b) Convey the object code in, or embodied in, a physical product 293 | (including a physical distribution medium), accompanied by a 294 | written offer, valid for at least three years and valid for as 295 | long as you offer spare parts or customer support for that product 296 | model, to give anyone who possesses the object code either (1) a 297 | copy of the Corresponding Source for all the software in the 298 | product that is covered by this License, on a durable physical 299 | medium customarily used for software interchange, for a price no 300 | more than your reasonable cost of physically performing this 301 | conveying of source, or (2) access to copy the 302 | Corresponding Source from a network server at no charge. 303 | 304 | c) Convey individual copies of the object code with a copy of the 305 | written offer to provide the Corresponding Source. This 306 | alternative is allowed only occasionally and noncommercially, and 307 | only if you received the object code with such an offer, in accord 308 | with subsection 6b. 309 | 310 | d) Convey the object code by offering access from a designated 311 | place (gratis or for a charge), and offer equivalent access to the 312 | Corresponding Source in the same way through the same place at no 313 | further charge. You need not require recipients to copy the 314 | Corresponding Source along with the object code. If the place to 315 | copy the object code is a network server, the Corresponding Source 316 | may be on a different server (operated by you or a third party) 317 | that supports equivalent copying facilities, provided you maintain 318 | clear directions next to the object code saying where to find the 319 | Corresponding Source. Regardless of what server hosts the 320 | Corresponding Source, you remain obligated to ensure that it is 321 | available for as long as needed to satisfy these requirements. 322 | 323 | e) Convey the object code using peer-to-peer transmission, provided 324 | you inform other peers where the object code and Corresponding 325 | Source of the work are being offered to the general public at no 326 | charge under subsection 6d. 327 | 328 | A separable portion of the object code, whose source code is excluded 329 | from the Corresponding Source as a System Library, need not be 330 | included in conveying the object code work. 331 | 332 | A "User Product" is either (1) a "consumer product", which means any 333 | tangible personal property which is normally used for personal, family, 334 | or household purposes, or (2) anything designed or sold for incorporation 335 | into a dwelling. In determining whether a product is a consumer product, 336 | doubtful cases shall be resolved in favor of coverage. For a particular 337 | product received by a particular user, "normally used" refers to a 338 | typical or common use of that class of product, regardless of the status 339 | of the particular user or of the way in which the particular user 340 | actually uses, or expects or is expected to use, the product. A product 341 | is a consumer product regardless of whether the product has substantial 342 | commercial, industrial or non-consumer uses, unless such uses represent 343 | the only significant mode of use of the product. 344 | 345 | "Installation Information" for a User Product means any methods, 346 | procedures, authorization keys, or other information required to install 347 | and execute modified versions of a covered work in that User Product from 348 | a modified version of its Corresponding Source. The information must 349 | suffice to ensure that the continued functioning of the modified object 350 | code is in no case prevented or interfered with solely because 351 | modification has been made. 352 | 353 | If you convey an object code work under this section in, or with, or 354 | specifically for use in, a User Product, and the conveying occurs as 355 | part of a transaction in which the right of possession and use of the 356 | User Product is transferred to the recipient in perpetuity or for a 357 | fixed term (regardless of how the transaction is characterized), the 358 | Corresponding Source conveyed under this section must be accompanied 359 | by the Installation Information. But this requirement does not apply 360 | if neither you nor any third party retains the ability to install 361 | modified object code on the User Product (for example, the work has 362 | been installed in ROM). 363 | 364 | The requirement to provide Installation Information does not include a 365 | requirement to continue to provide support service, warranty, or updates 366 | for a work that has been modified or installed by the recipient, or for 367 | the User Product in which it has been modified or installed. Access to a 368 | network may be denied when the modification itself materially and 369 | adversely affects the operation of the network or violates the rules and 370 | protocols for communication across the network. 371 | 372 | Corresponding Source conveyed, and Installation Information provided, 373 | in accord with this section must be in a format that is publicly 374 | documented (and with an implementation available to the public in 375 | source code form), and must require no special password or key for 376 | unpacking, reading or copying. 377 | 378 | 7. Additional Terms. 379 | 380 | "Additional permissions" are terms that supplement the terms of this 381 | License by making exceptions from one or more of its conditions. 382 | Additional permissions that are applicable to the entire Program shall 383 | be treated as though they were included in this License, to the extent 384 | that they are valid under applicable law. If additional permissions 385 | apply only to part of the Program, that part may be used separately 386 | under those permissions, but the entire Program remains governed by 387 | this License without regard to the additional permissions. 388 | 389 | When you convey a copy of a covered work, you may at your option 390 | remove any additional permissions from that copy, or from any part of 391 | it. (Additional permissions may be written to require their own 392 | removal in certain cases when you modify the work.) You may place 393 | additional permissions on material, added by you to a covered work, 394 | for which you have or can give appropriate copyright permission. 395 | 396 | Notwithstanding any other provision of this License, for material you 397 | add to a covered work, you may (if authorized by the copyright holders of 398 | that material) supplement the terms of this License with terms: 399 | 400 | a) Disclaiming warranty or limiting liability differently from the 401 | terms of sections 15 and 16 of this License; or 402 | 403 | b) Requiring preservation of specified reasonable legal notices or 404 | author attributions in that material or in the Appropriate Legal 405 | Notices displayed by works containing it; or 406 | 407 | c) Prohibiting misrepresentation of the origin of that material, or 408 | requiring that modified versions of such material be marked in 409 | reasonable ways as different from the original version; or 410 | 411 | d) Limiting the use for publicity purposes of names of licensors or 412 | authors of the material; or 413 | 414 | e) Declining to grant rights under trademark law for use of some 415 | trade names, trademarks, or service marks; or 416 | 417 | f) Requiring indemnification of licensors and authors of that 418 | material by anyone who conveys the material (or modified versions of 419 | it) with contractual assumptions of liability to the recipient, for 420 | any liability that these contractual assumptions directly impose on 421 | those licensors and authors. 422 | 423 | All other non-permissive additional terms are considered "further 424 | restrictions" within the meaning of section 10. If the Program as you 425 | received it, or any part of it, contains a notice stating that it is 426 | governed by this License along with a term that is a further 427 | restriction, you may remove that term. If a license document contains 428 | a further restriction but permits relicensing or conveying under this 429 | License, you may add to a covered work material governed by the terms 430 | of that license document, provided that the further restriction does 431 | not survive such relicensing or conveying. 432 | 433 | If you add terms to a covered work in accord with this section, you 434 | must place, in the relevant source files, a statement of the 435 | additional terms that apply to those files, or a notice indicating 436 | where to find the applicable terms. 437 | 438 | Additional terms, permissive or non-permissive, may be stated in the 439 | form of a separately written license, or stated as exceptions; 440 | the above requirements apply either way. 441 | 442 | 8. Termination. 443 | 444 | You may not propagate or modify a covered work except as expressly 445 | provided under this License. Any attempt otherwise to propagate or 446 | modify it is void, and will automatically terminate your rights under 447 | this License (including any patent licenses granted under the third 448 | paragraph of section 11). 449 | 450 | However, if you cease all violation of this License, then your 451 | license from a particular copyright holder is reinstated (a) 452 | provisionally, unless and until the copyright holder explicitly and 453 | finally terminates your license, and (b) permanently, if the copyright 454 | holder fails to notify you of the violation by some reasonable means 455 | prior to 60 days after the cessation. 456 | 457 | Moreover, your license from a particular copyright holder is 458 | reinstated permanently if the copyright holder notifies you of the 459 | violation by some reasonable means, this is the first time you have 460 | received notice of violation of this License (for any work) from that 461 | copyright holder, and you cure the violation prior to 30 days after 462 | your receipt of the notice. 463 | 464 | Termination of your rights under this section does not terminate the 465 | licenses of parties who have received copies or rights from you under 466 | this License. If your rights have been terminated and not permanently 467 | reinstated, you do not qualify to receive new licenses for the same 468 | material under section 10. 469 | 470 | 9. Acceptance Not Required for Having Copies. 471 | 472 | You are not required to accept this License in order to receive or 473 | run a copy of the Program. Ancillary propagation of a covered work 474 | occurring solely as a consequence of using peer-to-peer transmission 475 | to receive a copy likewise does not require acceptance. However, 476 | nothing other than this License grants you permission to propagate or 477 | modify any covered work. These actions infringe copyright if you do 478 | not accept this License. Therefore, by modifying or propagating a 479 | covered work, you indicate your acceptance of this License to do so. 480 | 481 | 10. Automatic Licensing of Downstream Recipients. 482 | 483 | Each time you convey a covered work, the recipient automatically 484 | receives a license from the original licensors, to run, modify and 485 | propagate that work, subject to this License. You are not responsible 486 | for enforcing compliance by third parties with this License. 487 | 488 | An "entity transaction" is a transaction transferring control of an 489 | organization, or substantially all assets of one, or subdividing an 490 | organization, or merging organizations. If propagation of a covered 491 | work results from an entity transaction, each party to that 492 | transaction who receives a copy of the work also receives whatever 493 | licenses to the work the party's predecessor in interest had or could 494 | give under the previous paragraph, plus a right to possession of the 495 | Corresponding Source of the work from the predecessor in interest, if 496 | the predecessor has it or can get it with reasonable efforts. 497 | 498 | You may not impose any further restrictions on the exercise of the 499 | rights granted or affirmed under this License. For example, you may 500 | not impose a license fee, royalty, or other charge for exercise of 501 | rights granted under this License, and you may not initiate litigation 502 | (including a cross-claim or counterclaim in a lawsuit) alleging that 503 | any patent claim is infringed by making, using, selling, offering for 504 | sale, or importing the Program or any portion of it. 505 | 506 | 11. Patents. 507 | 508 | A "contributor" is a copyright holder who authorizes use under this 509 | License of the Program or a work on which the Program is based. The 510 | work thus licensed is called the contributor's "contributor version". 511 | 512 | A contributor's "essential patent claims" are all patent claims 513 | owned or controlled by the contributor, whether already acquired or 514 | hereafter acquired, that would be infringed by some manner, permitted 515 | by this License, of making, using, or selling its contributor version, 516 | but do not include claims that would be infringed only as a 517 | consequence of further modification of the contributor version. For 518 | purposes of this definition, "control" includes the right to grant 519 | patent sublicenses in a manner consistent with the requirements of 520 | this License. 521 | 522 | Each contributor grants you a non-exclusive, worldwide, royalty-free 523 | patent license under the contributor's essential patent claims, to 524 | make, use, sell, offer for sale, import and otherwise run, modify and 525 | propagate the contents of its contributor version. 526 | 527 | In the following three paragraphs, a "patent license" is any express 528 | agreement or commitment, however denominated, not to enforce a patent 529 | (such as an express permission to practice a patent or covenant not to 530 | sue for patent infringement). To "grant" such a patent license to a 531 | party means to make such an agreement or commitment not to enforce a 532 | patent against the party. 533 | 534 | If you convey a covered work, knowingly relying on a patent license, 535 | and the Corresponding Source of the work is not available for anyone 536 | to copy, free of charge and under the terms of this License, through a 537 | publicly available network server or other readily accessible means, 538 | then you must either (1) cause the Corresponding Source to be so 539 | available, or (2) arrange to deprive yourself of the benefit of the 540 | patent license for this particular work, or (3) arrange, in a manner 541 | consistent with the requirements of this License, to extend the patent 542 | license to downstream recipients. "Knowingly relying" means you have 543 | actual knowledge that, but for the patent license, your conveying the 544 | covered work in a country, or your recipient's use of the covered work 545 | in a country, would infringe one or more identifiable patents in that 546 | country that you have reason to believe are valid. 547 | 548 | If, pursuant to or in connection with a single transaction or 549 | arrangement, you convey, or propagate by procuring conveyance of, a 550 | covered work, and grant a patent license to some of the parties 551 | receiving the covered work authorizing them to use, propagate, modify 552 | or convey a specific copy of the covered work, then the patent license 553 | you grant is automatically extended to all recipients of the covered 554 | work and works based on it. 555 | 556 | A patent license is "discriminatory" if it does not include within 557 | the scope of its coverage, prohibits the exercise of, or is 558 | conditioned on the non-exercise of one or more of the rights that are 559 | specifically granted under this License. You may not convey a covered 560 | work if you are a party to an arrangement with a third party that is 561 | in the business of distributing software, under which you make payment 562 | to the third party based on the extent of your activity of conveying 563 | the work, and under which the third party grants, to any of the 564 | parties who would receive the covered work from you, a discriminatory 565 | patent license (a) in connection with copies of the covered work 566 | conveyed by you (or copies made from those copies), or (b) primarily 567 | for and in connection with specific products or compilations that 568 | contain the covered work, unless you entered into that arrangement, 569 | or that patent license was granted, prior to 28 March 2007. 570 | 571 | Nothing in this License shall be construed as excluding or limiting 572 | any implied license or other defenses to infringement that may 573 | otherwise be available to you under applicable patent law. 574 | 575 | 12. No Surrender of Others' Freedom. 576 | 577 | If conditions are imposed on you (whether by court order, agreement or 578 | otherwise) that contradict the conditions of this License, they do not 579 | excuse you from the conditions of this License. If you cannot convey a 580 | covered work so as to satisfy simultaneously your obligations under this 581 | License and any other pertinent obligations, then as a consequence you may 582 | not convey it at all. For example, if you agree to terms that obligate you 583 | to collect a royalty for further conveying from those to whom you convey 584 | the Program, the only way you could satisfy both those terms and this 585 | License would be to refrain entirely from conveying the Program. 586 | 587 | 13. Use with the GNU Affero General Public License. 588 | 589 | Notwithstanding any other provision of this License, you have 590 | permission to link or combine any covered work with a work licensed 591 | under version 3 of the GNU Affero General Public License into a single 592 | combined work, and to convey the resulting work. The terms of this 593 | License will continue to apply to the part which is the covered work, 594 | but the special requirements of the GNU Affero General Public License, 595 | section 13, concerning interaction through a network will apply to the 596 | combination as such. 597 | 598 | 14. Revised Versions of this License. 599 | 600 | The Free Software Foundation may publish revised and/or new versions of 601 | the GNU General Public License from time to time. Such new versions will 602 | be similar in spirit to the present version, but may differ in detail to 603 | address new problems or concerns. 604 | 605 | Each version is given a distinguishing version number. If the 606 | Program specifies that a certain numbered version of the GNU General 607 | Public License "or any later version" applies to it, you have the 608 | option of following the terms and conditions either of that numbered 609 | version or of any later version published by the Free Software 610 | Foundation. If the Program does not specify a version number of the 611 | GNU General Public License, you may choose any version ever published 612 | by the Free Software Foundation. 613 | 614 | If the Program specifies that a proxy can decide which future 615 | versions of the GNU General Public License can be used, that proxy's 616 | public statement of acceptance of a version permanently authorizes you 617 | to choose that version for the Program. 618 | 619 | Later license versions may give you additional or different 620 | permissions. However, no additional obligations are imposed on any 621 | author or copyright holder as a result of your choosing to follow a 622 | later version. 623 | 624 | 15. Disclaimer of Warranty. 625 | 626 | THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY 627 | APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT 628 | HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY 629 | OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, 630 | THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 631 | PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM 632 | IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF 633 | ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 634 | 635 | 16. Limitation of Liability. 636 | 637 | IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING 638 | WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS 639 | THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY 640 | GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE 641 | USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF 642 | DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD 643 | PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), 644 | EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF 645 | SUCH DAMAGES. 646 | 647 | 17. Interpretation of Sections 15 and 16. 648 | 649 | If the disclaimer of warranty and limitation of liability provided 650 | above cannot be given local legal effect according to their terms, 651 | reviewing courts shall apply local law that most closely approximates 652 | an absolute waiver of all civil liability in connection with the 653 | Program, unless a warranty or assumption of liability accompanies a 654 | copy of the Program in return for a fee. 655 | 656 | END OF TERMS AND CONDITIONS 657 | 658 | How to Apply These Terms to Your New Programs 659 | 660 | If you develop a new program, and you want it to be of the greatest 661 | possible use to the public, the best way to achieve this is to make it 662 | free software which everyone can redistribute and change under these terms. 663 | 664 | To do so, attach the following notices to the program. It is safest 665 | to attach them to the start of each source file to most effectively 666 | state the exclusion of warranty; and each file should have at least 667 | the "copyright" line and a pointer to where the full notice is found. 668 | 669 | 670 | Copyright (C) 671 | 672 | This program is free software: you can redistribute it and/or modify 673 | it under the terms of the GNU General Public License as published by 674 | the Free Software Foundation, either version 3 of the License, or 675 | (at your option) any later version. 676 | 677 | This program is distributed in the hope that it will be useful, 678 | but WITHOUT ANY WARRANTY; without even the implied warranty of 679 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 680 | GNU General Public License for more details. 681 | 682 | You should have received a copy of the GNU General Public License 683 | along with this program. If not, see . 684 | 685 | Also add information on how to contact you by electronic and paper mail. 686 | 687 | If the program does terminal interaction, make it output a short 688 | notice like this when it starts in an interactive mode: 689 | 690 | Copyright (C) 691 | This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. 692 | This is free software, and you are welcome to redistribute it 693 | under certain conditions; type `show c' for details. 694 | 695 | The hypothetical commands `show w' and `show c' should show the appropriate 696 | parts of the General Public License. Of course, your program's commands 697 | might be different; for a GUI interface, you would use an "about box". 698 | 699 | You should also get your employer (if you work as a programmer) or school, 700 | if any, to sign a "copyright disclaimer" for the program, if necessary. 701 | For more information on this, and how to apply and follow the GNU GPL, see 702 | . 703 | 704 | The GNU General Public License does not permit incorporating your program 705 | into proprietary programs. If your program is a subroutine library, you 706 | may consider it more useful to permit linking proprietary applications with 707 | the library. If this is what you want to do, use the GNU Lesser General 708 | Public License instead of this License. But first, please read 709 | . 710 | --------------------------------------------------------------------------------