tuya-devices

Lightweight Node.js library for discovering and interacting with Tuya devices on local networks.

This project is used by the Node-RED node node-red-contrib-tuya-devices and can be incorporated into other Node.js projects.

Status

Active development. Core discovery, parsing and basic helpers are implemented; see lib/ for modules and tests under test/.

Features

• Passive discovery: listens on UDP ports used by Tuya devices (6666, 6667, 7000).
• Active discovery: optionally sends client discovery probes to trigger device responses (useful for newer devices that no longer broadcast).
• Multi-interface support: selects the correct local interface automatically when devices announce from different VLANs.
• Configurable broadcast behavior and intervals.

Installation

Install via npm (from your project root):

npm install

Quick start

Example showing the Scanner usage and scanner configuration options:

const Scanner = require('./lib/scanner')

const scanner = new Scanner(null, {
	scanner: {
		// optional: force which local interface IP to use
		// localIp: '192.168.1.42',

		// optional: choose broadcast address or leave to computed value
		// broadcastIp: '192.168.1.255',

		// broadcastMode: 'auto' | 'limited' | 'global' (default 'auto')
		// - 'auto' tries limited (subnet) broadcast then falls back to global
		// - 'limited' uses subnet broadcast only
		// - 'global' uses 255.255.255.255
		broadcastMode: 'auto',

		broadcastPorts: [7000, 6668],
		broadcastIntervalMs: 300000
	},
	debug: { Scanner: true }
})

scanner.on('find', device => console.log('found device', device))
scanner.on('need-config', info => console.warn('scanner needs config', info))
scanner.on('network-selected', info => console.info('network selected', info))

scanner.start()

Scanner configuration options

• scanner.localIp — (optional) Force use of this local IPv4 address for active discovery. If omitted, the library will auto-detect interfaces and pick one when a device announces.
• scanner.broadcastIp — (optional) Broadcast destination IP; when not set the library will compute subnet broadcast or use 255.255.255.255 depending on broadcastMode.
• scanner.broadcastPorts — (optional) Array of destination ports for discovery probes. Default is [7000, 6668, 6667]. Common Tuya local control ports are 6668 and 6667, and some devices also reply to 7000.
• scanner.broadcastIntervalMs — (optional, default 300000) Repeat interval for active discovery probes.
• scanner.broadcastMode — (optional, default 'auto') One of auto, limited, or global (see Quick start comments).
• scanner.broadcastAllInterfaces — (optional, default false) If set to true, the scanner sends active discovery probes on all detected local IPv4 interfaces instead of waiting for a device announcement to select the right interface.

Events

• find — emitted for each discovered device (payload contains parsed announcement including gwId, ip, etc.).
• need-config — emitted when active discovery cannot run because no suitable local IPv4 interface is available; payload contains a reason and message.
• network-selected — emitted when the library auto-selects a local interface for active discovery; payload: { local, netmask, broadcast }.
• error-parser — parsing errors from received messages.
• error-listener — socket/listener errors.

Development & Tests

Run unit tests under the test/ folder:

npm test

Contributing

PRs welcome. Please follow the existing code style: catch and else should start on their own line, and use multi-line if/else blocks.

License

See the LICENSE file in the repository.