Example plugins demonstrating the plugin architecture. Each plugin includes a manifest and implementation.

Plugin Structure

1
2
3
4

shelly-example/
├── manifest.json     # Plugin metadata and hooks
├── README.md         # Documentation
└── shelly-example    # Executable (bash, go binary, python, etc.)

Installation

1
2
3
4
5
6
7
8

# Copy plugin to plugins directory
cp -r examples/plugins/shelly-notify ~/.config/shelly/plugins/

# Enable plugins
shelly config set plugins.enabled true

# List installed plugins
shelly plugin list

shelly-tasmota

Tasmota device support for shelly-cli - detect, monitor, and control Tasmota-based smart home devices

Manifest

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

{
  "schema_version": "1",
  "name": "tasmota",
  "version": "1.0.0",
  "description": "Tasmota device support for shelly-cli - detect, monitor, and control Tasmota-based smart home devices",
  "capabilities": {
    "device_detection": true,
    "platform": "tasmota",
    "components": ["switch", "light", "sensor", "energy"],
    "firmware_updates": true,
    "hints": {
      "scene": "Tasmota uses Rules for automation. See: https://tasmota.github.io/docs/Rules/",
      "script": "Tasmota uses Berry scripting on ESP32. See: https://tasmota.github.io/docs/Berry/",
      "schedule": "Tasmota uses Timers for scheduling. See: https://tasmota.github.io/docs/Timers/",
      "kvs": "Tasmota uses Var and Mem commands for persistent storage. See: https://tasmota.github.io/docs/Commands/#control",
      "webhook": "Tasmota can send HTTP requests via Rules. See: https://tasmota.github.io/docs/Rules/#rule-trigger",
      "virtual": "Tasmota does not support virtual components"
    }
  },
  "hooks": {
    "detect": "./shelly-tasmota detect",
    "status": "./shelly-tasmota status",
    "control": "./shelly-tasmota control",
    "check_updates": "./shelly-tasmota check-updates",
    "apply_update": "./shelly-tasmota apply-update"
  },
  "minimum_shelly_version": "1.0.0"
}

Documentation

A plugin for shelly-cli that provides full integration with Tasmota-based smart home devices.

Features

• Device Detection: Automatically discover Tasmota devices during shelly discover
• Status Monitoring: View power state, sensors, and energy metrics
• Device Control: Control relays, switches, and lights with standard shelly-cli commands
• Firmware Updates: Check for and apply Tasmota firmware updates

Supported Devices

Any device running Tasmota firmware, including:

• Sonoff Basic, S20, S26, Pow series
• Shelly devices flashed with Tasmota
• Tuya-based smart plugs and switches
• ESP8266/ESP32 devices with Tasmota installed

Installation

From Source

1
2
3
4
5

cd examples/plugins/shelly-tasmota
go build -o shelly-tasmota .

# Install the plugin
shelly plugin install ./

Manual Installation

1. Build the plugin binary:

   1	go build -o shelly-tasmota .

2. Copy to the plugins directory:

   1 2	mkdir -p ~/.config/shelly-cli/plugins/shelly-tasmota cp shelly-tasmota manifest.json ~/.config/shelly-cli/plugins/shelly-tasmota/

3. Verify installation:

   1	shelly plugin list

Usage

Device Discovery

Tasmota devices are automatically detected during discovery:

1
2
3
4
5
6
7
8

# Discover all devices (Shelly and Tasmota)
shelly discover

# Discover only Tasmota devices
shelly discover --platform tasmota

# Skip plugin detection (Shelly only)
shelly discover --skip-plugins

Device Registration

Register a discovered Tasmota device:

1
2
3
4
5

# During discovery, select the device to register
shelly discover --register

# Or manually add with platform specified
shelly device add garage-plug 192.168.1.50 --platform tasmota

Device Status

View status of a Tasmota device:

1

shelly device status garage-plug

Output:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

Device: garage-plug
Platform: tasmota
Model: Sonoff Basic R3
Address: 192.168.1.50

  Status: Online

Components
COMPONENT   STATE
switch:0    on

Sensors
SENSOR      VALUE
wifi_rssi   -52 dBm

Energy
  Power:   45.3 W
  Voltage: 121.5 V
  Current: 0.372 A
  Total:   123.456 kWh

Device Control

Control Tasmota devices with standard commands:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# Turn on
shelly switch on garage-plug

# Turn off
shelly switch off garage-plug

# Toggle
shelly switch toggle garage-plug

# Control specific relay on multi-channel devices
shelly switch on garage-plug --id 1

Firmware Updates

Check and apply firmware updates:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# Check for updates on a specific device
shelly firmware check garage-plug

# Check all devices (including Tasmota)
shelly firmware check --all

# Interactive update workflow
shelly firmware updates

# Update all Tasmota devices to stable
shelly firmware updates --all --platform tasmota --yes

# Update to beta/development release
shelly firmware updates --devices garage-plug --beta --yes

Firmware Update Workflow

The plugin integrates with the official Tasmota OTA server:

1. Stable releases: http://ota.tasmota.com/tasmota/release/
2. Development builds: http://ota.tasmota.com/tasmota/

The plugin automatically:

• Detects the chip type (ESP8266/ESP32)
• Uses the appropriate OTA URL
• Checks GitHub for the latest version
• Compares with the installed version

Custom Firmware URL

For custom builds or specific variants:

1

shelly firmware update garage-plug --url http://example.com/custom-tasmota.bin.gz

Authentication

For password-protected Tasmota devices, use the auth flags:

1

shelly device status garage-plug --auth-user admin --auth-pass secret

Or configure in ~/.config/shelly-cli/config.yaml:

1
2
3
4
5
6
7

devices:
  garage-plug:
    address: 192.168.1.50
    platform: tasmota
    auth:
      username: admin
      password: secret

Component Types

The plugin supports these Tasmota component types:

Troubleshooting

Device Not Detected

1. Ensure the device is on the same network
2. Verify Tasmota web interface is accessible: http://<device-ip>
3. Check firewall settings for port 80

Authentication Errors

1. Verify username and password in device config
2. For devices without authentication, ensure auth is disabled in Tasmota settings

Firmware Update Fails

1. Ensure device has enough free memory
2. Check network connectivity
3. For ESP8266 devices, ensure you’re using the correct variant (tasmota.bin.gz)

GitHub Rate Limiting

The plugin queries GitHub API for version checks. Unauthenticated requests are limited to 60/hour. If you encounter rate limiting:

1. Wait for the rate limit to reset (1 hour)
2. Or run firmware checks less frequently

Development

Building

1
2

cd examples/plugins/shelly-tasmota
go build -o shelly-tasmota .

Testing Hooks Manually

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# Test detection
./shelly-tasmota detect --address 192.168.1.50

# Test status
./shelly-tasmota status --address 192.168.1.50

# Test control
./shelly-tasmota control --address 192.168.1.50 --action on --component switch --id 0

# Test firmware check
./shelly-tasmota check-updates --address 192.168.1.50

# Test firmware apply
./shelly-tasmota apply-update --address 192.168.1.50 --stage stable

Hook Response Formats

All hooks return JSON. See types.go for the complete response schemas.

Known Limitations

1. No Real-Time Events: Tasmota requires polling (no WebSocket support like Shelly)
2. Rules/Berry: Tasmota Rules and Berry scripting are not exposed via shelly-cli
3. GPIO Configuration: Template and GPIO configuration is not supported
4. Backup/Restore: Device backup/restore uses different format than Shelly

License

MIT License - see the main shelly-cli repository for details.