Merge pull request #319 from hermanos-energy/add_tasmota_blue_print

add tasmota blueprint

.marketplace/devices/devices.yml

@@ -797,3 +797,13 @@
   blueprint_options:
     - blueprint: fuel_cells/efoy_h2_cabinet_n_series
       verification_level: ready_for_testing
+
+- id: tasmota
+  display_name: Tasmota
+  description: Any product running on Tasmota firmware
+  icon: enapter-microchip
+  vendor: tasmota
+  category: relays
+  blueprint_options:
+    - blueprint: relays/tasmota
+      verification_level: ready_for_testing

.marketplace/vendors/vendors.yml

@@ -252,3 +252,8 @@
   display_name: EFOY
   icon_url: https://raw.githubusercontent.com/Enapter/marketplace/main/.marketplace/vendors/icons/efoy.png
   website: https://www.efoy.com/
+
+- id: tasmota
+  display_name: Tasmota
+  icon_url: https://raw.githubusercontent.com/Enapter/marketplace/main/.marketplace/vendors/icons/tasmota.png
+  website: https://tasmota.github.io/docs/

relays/tasmota/README.md

@@ -0,0 +1,30 @@
+# Generic Tasmota
+
+This [Enapter Device Blueprint](https://github.com/Enapter/marketplace#blue_book-enapter-device-blueprints) is meant to integrate with any [Tasmota](https://tasmota.github.io/docs/) device. **Tasmota** is opensource firmware, it runs on the ESP32 & ESP8266 chip. Tasmota firmware forms the basis for a lot of smart relays, smart sensors, smart sockets including loads of commercial vendors like [Nous](https://nous.technology/). But the ESP32 & ESP8266 essentially are very small webservers on a chip, and you can include them in any circuit board, so the combination of a chip, the tasmota firmware, and this blue print enables you to connect any device to the enapter cloud.
+
+The blueprint essentially is a wrapper around the Tasmota interface. It enables all commands which are supported by the tasmota device. This makes it a very powerful interface, but it also exposes a potential security thread. You should probably disable some commands on the tasmota firmware, or disable the generic command in this blueprint and only enable the once for your use case.
+
+## Setup
+
+The Tasmota device and the gateway must be able to communicate with each other over a local IP, so make sure that they are linked to the same network.
+
+For any specific questions about Tasmota look at the [Tasmota docs](https://tasmota.github.io/docs/).
+
+## Set up config
+
+Make sure to configure the device before you start using it, using the configure command. The configuration has two parameters:
+
+1. The ADDRESS property should be filled with the local IP address for example 192.168.8.212 over which the gateway can connect to the device.
+2. The PASSWORD property is optional, it is only required if the Tasmota is set up in such a way that a password is required to connect to the api. Be aware that it is only a very thin layer of extra security and you should not depend purely on this feature for your security strategy.
+
+## Command
+
+There are three commands to control the device
+
+1. turn_on will turn on the device
+2. turn_off will turn the device off
+3. tasmota_command is a generic command. You can pass in any commands supported by your device, a full list of commands can be found here [Tasmota Commands](https://tasmota.github.io/docs/Commands). Some commands are supported by all tasmota devices, but others are device specific the command MP3Play for example will play a song on a mp3 player running on Tasmota, and obviously won't have any effect on a smart plug.
+
+## Telemetry
+
+The blueprint sends one telemetry input showing if the device is on or off. There is much more telemetry data available, you should probably modify the example for your own use case.

relays/tasmota/firmware.lua

@@ -0,0 +1,77 @@
+json = require('json')
+connection = http.client({ timeout = 10 })
+local config = require('enapter.ucm.config')
+
+-- The addres is the local IP adres of the tasmota device
+-- The password is optional it is only needed in case the web-admin pasword is set on the tasmota device,
+-- be aware that this is only a very thin extra layer of security and you should not purely rely on that.
+ADDRESS = 'address'
+PASSWORD = 'password'
+
+function main()
+  config.init({
+    [PASSWORD] = { type = 'string', required = false },
+    [ADDRESS] = { type = 'string', required = true, default = '127.0.0.1' },
+  })
+  enapter.register_command_handler('turn_on', function()
+    return control_device('Power%20On')
+  end)
+  enapter.register_command_handler('turn_off', function()
+    return control_device('Power%20Off')
+  end)
+  enapter.register_command_handler('tasmota_command', tasmota_command)
+  scheduler.add(30000, send_properties)
+  scheduler.add(1000, send_telemetry)
+end
+
+function tasmota_command(ctx, args)
+  ctx.log('command arrived ' .. args['command'])
+  return control_device(args['command'])
+end
+
+function send_properties()
+  enapter.send_properties({
+    model = 'TASMOTA',
+  })
+end
+
+-- Sends status, change for your specific requirements
+function send_telemetry()
+  local tasmota_status = control_device('Status0')
+  local decoded_status = json.decode(tasmota_status) -- The status line contains all kind of info
+  local power = decoded_status.Status.Power -- Access the "Power" field
+  local power_status = (power == 1) and 'on' or 'off'
+  enapter.send_telemetry({ status = power_status })
+end
+
+-- Generic function to control the device
+function control_device(command)
+  local config_values, err = config.read_all()
+
+  if err then
+    enapter.log('Could not read config: ' .. err)
+  end
+
+  local url = 'http://' .. config_values[ADDRESS] .. '/cm?cmnd=' .. command
+
+  -- Add user and password only if password is provided
+  if config_values[PASSWORD] and config_values[PASSWORD] ~= '' then
+    url = url .. '&user=admin&password=' .. config_values[PASSWORD]
+  end
+
+  local response, error = connection:get(url)
+
+  if error then
+    enapter.log('HTTP request failed: ' .. error)
+    return error
+  end
+
+  if response and response.body then
+    enapter.log('Result for command (' .. command .. '): ' .. response.body)
+    return response.body
+  else
+    enapter.log('No response body or invalid response format for command: ' .. command)
+  end
+end
+
+main()

relays/tasmota/manifest.yml

@@ -0,0 +1,88 @@
+# Manifest for blueprint connection to any Tasmota device
+
+blueprint_spec: device/1.0
+
+display_name: Tasmota device
+description: A wrapper around the Tasmota interface to connect to any Tasmota powered device.
+icon: light-switch
+vendor: tasmota
+author: hermanos-energy
+support:
+  url: https://go.enapter.com/enapter-blueprint-support
+  email: [email protected]
+contributors:
+  - SoloJan
+license: MIT
+
+
+communication_module:
+  product: ENP-VIRTUAL
+  lua:
+    file: firmware.lua
+    dependencies:
+      - enapter-ucm
+
+properties:
+  serial_number:
+    type: string
+    display_name: Serial Number
+  model:
+    type: string
+    display_name: Model
+
+telemetry:
+  status:
+    display_name: Status
+    type: string
+    enum:
+      - "on"
+      - "off"
+
+commands:
+  turn_on:
+    display_name: Turn on
+    group: tasmota
+    ui:
+      icon: led-on
+      quick_access: true
+  turn_off:
+    display_name: Turn off
+    group: tasmota
+    ui:
+      icon: led-of
+      quick_access: true
+  tasmota_command:
+    arguments:
+      command:
+        display_name: command
+        description: A valid tasmota command,
+        type: string
+        required: true
+    display_name: Send any command
+    group: tasmota
+  write_configuration:
+    display_name: Configure
+    group: config
+    populate_values_command: read_configuration
+    ui:
+      icon: file-document-edit-outline
+    arguments:
+      address:
+        display_name: ip address
+        type: string
+        required: true
+      password:
+        display_name: password
+        type: string
+        required: false
+  read_configuration:
+    display_name: Read config Parameters
+    group: config
+    ui:
+      icon: file-check-outline
+
+command_groups:
+  config:
+    display_name: Configuration
+  tasmota:
+    display_name: Tasmota commands