IoTap is a command-line interface tool for tapping into IoT devices, designed to simplify their management and configuration on a large scale.
Born out of necessity, this tool fills a critical gap, offering a solution where none previously existed—particularly for managing extensive IoT deployments.
It is especially effective for performing batch operations and maintaining uniform device management.
- Perform network-wide device scanning and discovery.
- Run commands across multiple devices simultaneously.
- Export detailed device information as CSV or JSON to a file or on-screen.
- Apply configurations to multiple devices.
- Activate/deactivate device authentication mechanisms.
- Identify devices running outdated software versions.
- Update firmware on outdated devices.
- Perform remote device restarts.
- Easy script deployment across compatible devices.
- Go (version 1.23 or later)
- Network access to supported IoT devices
You can install the tool using one of the following methods.
Download precompiled binaries from the releases page.
Binaries are available for:
- Linux (AMD64)
- Windows (AMD64)
- macOS (Apple Silicon)
Clone the repository and compile the code manually to build the tool from the latest source.
git clone https://github.com/quetzyg/IoTap.git
cd IoTap
go build -o iotap
sudo mv iotap /usr/local/bin/iotap <IP|CIDR> <command> [flags]<IP|CIDR>: A single IP address (e.g. 192.168.1.1) or a CIDR notation (e.g. 192.168.1.0/24).<command>: The command to be executed for each resolved IP.[flags]: Optional parameters to customise the command execution.
dump: Output device scan results to STDOUT or to a file
# Dump device results to screen in CSV format (default)
iotap 192.168.1.0/24 dump
# Dump device results in CSV format to a file
iotap 192.168.1.0/24 dump -o devices.csv
# Dump device results in JSON format to a file
iotap 192.168.1.0/24 dump -o devices.json -f json
# Dump Shelly Gen2 only device results to the screen, sorted by IP
iotap 192.168.1.0/24 dump -d shellygen2 -s ipDump command help:
iotap 192.168.1.0/24 dump -hOutput:
Usage of dump:
./iotap <IP|CIDR> dump [flags]
Flags:
-d value
Device driver (default all)
-f value
Dump format (default csv)
-o string
Scan results output file
-s value
Sort devices by field (default name)config: Apply a configuration to multiple devices
# Apply the configuration from `config.json` to all Shelly Gen1 devices
iotap 192.168.1.0/24 config -d shellygen1 -c config.jsonConfiguration command help:
iotap 192.168.1.0/24 config -hOutput:
Usage of config:
./iotap <IP|CIDR> config [flags]
Flags:
-c string
Device configuration file
-d value
Device driver (default all)secure: Enable/disable device authentication
# Disable the authentication on all Shelly Gen1 devices
iotap 192.168.1.0/24 secure -d shellygen1 --off# Enable the authentication on all devices
iotap 192.168.1.0/24 secure -c authentication.jsonSecure command help:
iotap 192.168.1.0/24 config -hOutput:
Usage of secure:
./iotap <IP|CIDR> secure [flags]
Flags:
-c string
Auth configuration file (incompatible with --off)
-d value
Device driver (default all)
-off
Turn device authentication off (incompatible with -c)version: Scan and check device versions
Identify device versions across the network, listing any that are out of date.# Check versions for all devices
iotap 192.168.1.0/24 version
# Check versions of specific devices (Shelly Gen2)
iotap 192.168.1.0/24 version -d shellygen2Version command help:
iotap 192.168.1.0/24 version -hOutput:
Usage of version:
./iotap <IP|CIDR> version [flags]
Flags:
-d value
Device driver (default all)update: Update outdated devices
Update devices to the latest available vendor firmware.# Update the firmware for all devices
iotap 192.168.1.0/24 update
# Update the firmware for specific devices (Shelly Gen1)
iotap 192.168.1.0/24 update -d shellygen1Update command help:
iotap 192.168.1.0/24 update -hOutput:
Usage of update:
./iotap <IP|CIDR> update [flags]
Flags:
-d value
Device driver (default all)deploy: Deploy scripts to devices
# Perform a deployment to Shelly Gen2 devices
iotap 192.168.1.0/24 deploy -d shellygen2 -c deployment.jsonDeploy command help:
iotap 192.168.1.0/24 deploy -hOutput:
Usage of deploy:
./iotap <IP|CIDR> deploy [flags]
Flags:
-c string
Deployment configuration file
-d value
Device driver (default all)Warning
As part of the deployment task, the deploy command will remove any previously existing scripts from the device.
reboot: Restart devices
# Reboot all devices
iotap 192.168.1.0/24 reboot
# Reboot devices by a specific driver
iotap 192.168.1.0/24 reboot -d shellygen1Reboot command help:
iotap 192.168.1.0/24 reboot -hOutput:
Usage of reboot:
./iotap <IP|CIDR> reboot [flags]
Flags:
-d value
Device driver (default all)The only configuration that may be required is a set of credentials.
These must match the ones used when authentication was first enabled on the target devices.
The configuration can be loaded in two ways:
-
Environment Variables:
- Credentials can be set using the following environment variables:
export IOTAP_USERNAME=admin export IOTAP_PASSWORD=secret
- Credentials can be set using the following environment variables:
-
Predefined JSON File:
- The tool can load configuration from a JSON file located at
~/.config/iotap.json. - Example file content:
{ "credentials": { "username": "admin", "password": "secret" } }
- The tool can load configuration from a JSON file located at
Certain IoTap commands require a configuration file. These must be in the JSON format and are categorised as follows:
-
Device Configuration: Used with the
configcommand to define parameters for configuring one or more IoT devices. -
Authentication Configuration: Used with the
securecommand to specify the credentials that devices will use once authentication is enforced. -
Deployment Configuration: Used with the
deploycommand to provide paths to scripts for deployment on supported devices.
Each configuration file allows defining a Policy, to enable the inclusion or exclusion of devices based on criteria such as MAC address or device model.
Policies are a mechanism to selectively apply configurations to specific devices or groups of devices. By using these, users can:
-
Whitelist: Include only devices that match specified MAC addresses or device models.
-
Blacklist: Exclude devices that match specified MAC addresses or device models.
The device configuration file defines the parameters to be set on one or more IoT devices. This file enables users to customise the behavior and settings of the devices under management.
Currently, there are two device configuration types:
- Shelly Gen1
- Shelly Gen2
Each generation follows a distinct structure tailored to how the respective devices process and expect the data.
Shelly Gen1 Example
In this scenario, devices with MAC addresses AA:BB:CC:DD:EE:FF and 11:22:33:44:55:66 will be skipped, while the remaining discovered devices will be configured.
{
"meta": {
"device":"Shelly 1"
},
"policy": {
"mode": "blacklist",
"devices": [
"AA:BB:CC:DD:EE:FF",
"11:22:33:44:55:66"
]
},
"settings": {
"ap_roaming_enabled": true,
"ap_roaming_threshold": -70,
"mqtt_enable": true,
"mqtt_server": "192.168.1.254:1883",
"mqtt_clean_session": true,
"mqtt_retain": false,
"mqtt_user": "mosquitto",
"mqtt_pass": "P@ssw0rd",
"mqtt_reconnect_timeout_max": 60,
"mqtt_reconnect_timeout_min": 2,
"mqtt_keep_alive": 60,
"mqtt_update_period": 0,
"mqtt_max_qos": 2,
"coiot_enable": false,
"sntp_server": "time.cloudflare.com",
"discoverable": false,
"tzautodetect": true,
"led_status_disable": false,
"debug_enable": false,
"allow_cross_origin": false,
"wifirecovery_reboot_enabled": true
},
"settings_relay": [
{
"name": null,
"appliance_type": "lock",
"default_state": "off",
"btn_type": "detached",
"btn_reverse": true,
"auto_on": 0,
"auto_off": 3,
"schedule": false,
"schedule_rules": [
"0800-012345-on"
]
}
],
"settings_sta": {
"enabled": true,
"ssid": "WIFI",
"key": "P@ssw0rd",
"ipv4_method": "dhcp"
}
}Shelly Gen2 Example
In this scenario, only devices with models SNSW-001X16EU and SNSW-001X8EU will be configured.
{
"meta": {
"device": "Shelly Plus 1 & Shelly Plus 1 Mini"
},
"policy": {
"mode": "whitelist",
"models": [
"SNSW-001X16EU",
"SNSW-001X8EU"
]
},
"sys": {
"config": {
"device": {
"eco_mode": false,
"discoverable": false
},
"sntp": {
"server": "time.cloudflare.com"
},
"debug": {
"mqtt": {
"enable": false
},
"websocket": {
"enable": false
},
"udp": {
"addr": null
}
}
}
},
"input": [
{
"id": 0,
"config": {
"name": null,
"type": "switch",
"invert": true
}
}
],
"switch": [
{
"id": 0,
"config": {
"name": null,
"in_mode": "detached",
"initial_state": "off",
"auto_on": false,
"auto_off": true,
"auto_off_delay": 3
}
}
],
"wifi": {
"config": {
"ap": {
"enable": false,
"range_extender": {
"enable": false
}
},
"sta": {
"enable": true,
"ssid": "WIFI",
"pass": "P@ssw0rd",
"is_open": false,
"ipv4mode": "dhcp"
},
"sta1": {
"enable": false
}
}
},
"ble": {
"config": {
"enable": false
}
},
"cloud": {
"config": {
"enable": false
}
},
"mqtt": {
"config": {
"enable": true,
"server": "192.168.1.254:1883",
"user": "mosquitto",
"pass": "P@ssw0rd",
"ssl_ca": null,
"enable_rpc": true,
"rpc_ntf": false,
"status_ntf": true,
"enable_control": true
}
}
}The authentication configuration file specifies the credentials that one or more devices should use to enforce security.
Example
In this scenario, authentication will be set to any device that supports such feature.
{
"meta": {
"device": "All",
},
"credentials": {
"username": "admin",
"password": "secret"
}
}The deployment configuration file allows users to define paths to scripts that can be deployed to devices supporting script execution.
Example
In this scenario, scripts will only be deployed to devices where the model name is SPSW-001XE16EU.
{
"meta": {
"device": "Shelly Pro 1",
},
"policy": {
"mode": "whitelist",
"models": [
"SPSW-001XE16EU"
]
},
"scripts": [
"announce.js",
"detached_input_on.js"
]
}Important
Ensure the scripts you deploy are valid Shelly Script Language code.
The following table outlines the devices that have been successfully tested:
| Vendor | Generation | Model | Links |
|---|---|---|---|
| Shelly | Gen1 | Shelly 1 | KB, API |
| Shelly | Gen2 | Shelly Plus 1 | KB, API |
| Shelly | Gen2 | Shelly Plus 1 (Mini) | KB, API |
| Shelly | Gen2 | Shelly Pro 1 | KB, API |
While the above devices have been successfully tested, IoTap is designed with flexibility and broad compatibility in mind, meaning that it should support a greater number of Shelly Gen1 and Gen2 devices.
Device Compatibility Expansion:
- The maintainer is actively seeking to expand the device compatibility matrix
- Hardware vendors and manufacturers are invited to contribute by:
- Providing test devices
- Sponsoring programming costs
- Collaborating on compatibility testing
Current Product Support:
- Currently, the tool only supports Shelly products
- We welcome sponsorship and collaboration from other interested IoT and smart home device manufacturers
If you are a vendor, manufacturer, or potential sponsor interested in expanding our device support, please get in touch.
If you find this project helpful, consider supporting its development:
🏆 Sponsor on GitHub
This project is open to community input and feature suggestions. Enhancements that provide broad utility and solve common challenges for multiple users are prioritary. While creative ideas are welcome, implementation will be based on potential impact and alignment with the project's core objectives.
If you have a feature request, please submit it as an Idea in the Discussions—the more compelling the use case and potential benefit, the higher the likelihood of adoption.
Sponsored development: if you or your organisation want to accelerate a feature that has wide applicability, sponsorship can help move it to the top of the priority list.
Use responsibly! Always ensure you have proper authorisation before tapping into network devices.
Please review the security policy to ensure proper procedures for disclosing security vulnerabilities.
IoTap is open source software licensed under the Apache License 2.0.