tuyapi 7.2.0 | Documentation

TuyaDevice

Represents a Tuya device.

You must pass either an IP or an ID. If you're experiencing problems when only passing one, try passing both if possible.

new TuyaDevice(options: Object)

Extends EventEmitter

Parameters

options (Object = {})

Name	Description
options.ip `String?`	IP of device
options.port `Number` (default `6668`)	port of device
options.id `String?`	ID of device (also called `devId` )
options.gwID `String` (default `''`)	gateway ID (not needed for most devices), if omitted assumed to be the same as `options.id`
options.key `String`	encryption key of device (also called `localKey` )
options.productKey `String?`	product key of device (currently unused)
options.version `Number` (default `3.1`)	protocol version
options.nullPayloadOnJSONError `Boolean` (default `false`)	if true, emits a data event containing a payload of null values for on-device JSON parsing errors
options.issueGetOnConnect `Boolean` (default `true`)	if true, sends GET request after connection is established. This should probably be `false` in synchronous usage.
options.issueRefreshOnConnect `Boolean` (default `false`)	if true, sends DP_REFRESH request after connection is established. This should probably be `false` in synchronous usage.
options.issueRefreshOnPing `Boolean` (default `false`)	if true, sends DP_REFRESH and GET request after every ping. This should probably be `false` in synchronous usage.

Example

const tuya = new TuyaDevice({id: 'xxxxxxxxxxxxxxxxxxxx', key: 'xxxxxxxxxxxxxxxx'})

Instance Members

▸ get(options = {})

Gets a device's current status. Defaults to returning only the value of the first DPS index.

get(options: Object?): Promise<(Boolean | Object)>

Parameters

options (Object? = {})

Name	Description
options.schema `Boolean?`	true to return entire list of properties from device
options.dps `Number` (default `1`)	DPS index to return
options.cid `String?`	if specified, use device id of zigbee gateway and cid of subdevice to get its status

Returns

Promise<(Boolean | Object)>: returns boolean if single property is requested, otherwise returns object of results

Example

// get first, default property from device tuya.get().then(status => console.log(status))

// get second property from device tuya.get({dps: 2}).then(status => console.log(status))

// get all available data from device tuya.get({schema: true}).then(data => console.log(data))

▸ refresh(options = {})

Refresh a device's current status. Defaults to returning all values.

refresh(options: Object?): Promise<Object>

Parameters

options (Object? = {})

Name	Description
options.schema `Boolean?`	true to return entire list of properties from device
options.dps `Number` (default `1`)	DPS index to return
options.cid `String?`	if specified, use device id of zigbee gateway and cid of subdevice to refresh its status
options.requestedDPS `Array.Number` (default `[4,5,6,18,19,20]`)	only set this if you know what you're doing

Returns

Promise<Object>: returns object of results

Example

// get first, default property from device tuya.refresh().then(status => console.log(status))

// get second property from device tuya.refresh({dps: 2}).then(status => console.log(status))

// get all available data from device tuya.refresh({schema: true}).then(data => console.log(data))

▸ set(options)

Sets a property on a device.

set(options: Object): Promise<Object>

Parameters

options (Object)

Name	Description
options.dps `Number` (default `1`)	DPS index to set
options.set `any?`	value to set
options.cid `String?`	if specified, use device id of zigbee gateway and cid of subdevice to set its property
options.multiple `Boolean` (default `false`)	Whether or not multiple properties should be set with options.data
options.data `Object` (default `{}`)	Multiple properties to set at once. See above.
options.shouldWaitForResponse `Boolean` (default `true`)	see #420 and #421 for details

Returns

Promise<Object>: returns response from device

Example

// set default property tuya.set({set: true}).then(() => console.log('device was turned on'))

// set custom property tuya.set({dps: 2, set: false}).then(() => console.log('device was turned off'))

// set multiple properties tuya.set({ multiple: true, data: { '1': true, '2': 'white' }}).then(() => console.log('device was changed'))

// set custom property for a specific (virtual) deviceId tuya.set({ dps: 2, set: false, devId: '04314116cc50e346566e' }).then(() => console.log('device was turned off'))

▸ connect()

Connects to the device. Can be called even if device is already connected.

connect(): Promise<Boolean>

Returns

Promise<Boolean>: true if connect succeeds

▸ disconnect()

Disconnects from the device, use to close the socket and exit gracefully.

disconnect()

▸ isConnected()

Returns current connection status to device.

isConnected(): Boolean

Returns

Boolean: ( true if connected, false otherwise.)

▸ resolveId(options)

resolveId(options: any)

Deprecated: since v3.0.0. Will be removed in v4.0.0. Use find() instead.

Parameters

options (any)

▸ find(options = {})

Finds an ID or IP, depending on what's missing. If you didn't pass an ID or IP to the constructor, you must call this before anything else.

find(options: Object?): Promise<(Boolean | Array)>

Parameters

options (Object? = {})

Name	Description
options.timeout `Number` (default `10`)	how long, in seconds, to wait for device to be resolved before timeout error is thrown
options.all `Boolean?` (default `false`)	true to return array of all found devices

Returns

Promise<(Boolean | Array)>: true if ID/IP was found and device is ready to be used

Example

tuya.find().then(() => console.log('ready!'))

▸ toggle(property)

Toggles a boolean property.

toggle(property: Number): Promise<Boolean>

Parameters

property (Number = 1) property to toggle

Returns

Promise<Boolean>: the resulting state

TuyaDevice#error

Emitted on socket error, usually a result of a connection timeout. Also emitted on parsing errors.

TuyaDevice#error

Properties

error (Error) : error event

TuyaDevice#connected

Emitted when socket is connected to device. This event may be emitted multiple times within the same script, so don't use this as a trigger for your initialization code.

TuyaDevice#connected

TuyaDevice#heartbeat

Emitted when a heartbeat ping is returned.

TuyaDevice#heartbeat

TuyaDevice#dp-refresh

Emitted when dp_refresh data is proactive returned from device, omitting dps 1 Only changed dps are returned.

TuyaDevice#dp-refresh

Properties

data (Object) : received data

commandByte (Number) : commandByte of result( 8=proactive update from device)

sequenceN (Number) : the packet sequence number

TuyaDevice#data

Emitted when data is returned from device.

TuyaDevice#data

Properties

data (Object) : received data

commandByte (Number) : commandByte of result (e.g. 7=requested response, 8=proactive update from device)

sequenceN (Number) : the packet sequence number

TuyaDevice#disconnected

Emitted when a socket is disconnected from device. Not an exclusive event: error and disconnected may be emitted at the same time if, for example, the device goes off the network.

TuyaDevice#disconnected

Packet

A complete packet.

Packet

Type: Object

Properties

payload ((Buffer | Object | String)) : Buffer if hasn't been decoded, object or string if it has been

leftover (Buffer) : bytes adjacent to the parsed packet

commandByte (Number)

sequenceN (Number)

MessageParser

Low-level class for parsing packets.

new MessageParser(options: Object)

Parameters

options (Object = {})

Name	Description
options.key `String`	localKey of cipher
options.version `Number` (default `3.1`)	protocol version

Example

const parser = new MessageParser({key: 'xxxxxxxxxxxxxxxx', version: 3.1})

Instance Members

▸ parsePacket(buffer)

Parses a Buffer of data containing at least one complete packet at the begining of the buffer. Will return multiple packets if necessary.

parsePacket(buffer: Buffer): Packet

Parameters

buffer (Buffer) of data to parse

Returns

Packet: packet of data

▸ getPayload(data)

Attempts to decode a given payload into an object or string.

getPayload(data: Buffer): (Object | String)

Parameters

data (Buffer) to decode

Returns

(Object | String): object if payload is JSON, otherwise string

▸ parse(buffer)

Given a buffer potentially containing multiple packets, this parses and returns all of them.

parse(buffer: Buffer): Array<Packet>

Parameters

buffer (Buffer) to parse

Returns

Array<Packet>: parsed packets

▸ encode(options)

Encodes a payload into a Tuya-protocol-complient packet.

encode(options: Object): Buffer

Parameters

options (Object)

Name	Description
options.data `(Buffer \| String \| Object)`	data to encode
options.encrypted `Boolean`	whether or not to encrypt the data
options.commandByte `Number`	command byte of packet (use CommandType definitions)
options.sequenceN `Number?`	optional, sequence number

Returns

Buffer:

TuyaCipher

Low-level class for encrypting and decrypting payloads.

new TuyaCipher(options: Object)

Parameters

options (Object)

Name	Description
options.key `String`	localKey of cipher
options.version `Number`	protocol version

Example

const cipher = new TuyaCipher({key: 'xxxxxxxxxxxxxxxx', version: 3.1})

Instance Members

▸ encrypt(options)

Encrypts data.

encrypt(options: Object): (Buffer | String)

Parameters

options (Object)

Name	Description
options.data `String`	data to encrypt
options.base64 `Boolean` (default `true`)	`true` to return result in Base64

Returns

(Buffer | String): returns Buffer unless options.base64 is true

Example

TuyaCipher.encrypt({data: 'hello world'})

▸ decrypt(data)

Decrypts data.

decrypt(data: (String | Buffer)): (Object | String)

Parameters

data ((String | Buffer)) to decrypt

Returns

(Object | String): returns object if data is JSON, else returns string

▸ md5(data)

Calculates a MD5 hash.

md5(data: String): String

Parameters

data (String) to hash

Returns

String: characters 8 through 16 of hash of data

crc32

Computes a Tuya flavored CRC32

crc32(bytes: Iterable): Number

Parameters

bytes (Iterable)

Returns

Number: Tuya CRC32

tuyapi

TuyaDevice

Events

TuyaDevice#error

TuyaDevice#connected

TuyaDevice#heartbeat

TuyaDevice#dp-refresh

TuyaDevice#data

TuyaDevice#disconnected

Packet

MessageParser

TuyaCipher

crc32