ESP-TuyaBLE

KO | EN

gitlite — search

#hacktoberfest #typescript #go #golang #machine-learning #rust #docker #macos #nodejs #awesome #cli #kubernetes #mcp #open-source

(★ 12)

An ESP32 library to connect to Tuya BLE devices based on Arduino-NimBLE.

ESP-TuyaBLE Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# TuyaBLE

An ESP32 library to connect to Tuya BLE devices based on Arduino-NimBLE.

## How to use?

The core of the library is `TuyaBLEDevice`. This class contains the logic to connect to a Tuya device over BLE and do a key-exchange and get and set DataPoints.

## What are DataPoints?

Tuya smart devices communicate thru so-called DataPoints. A DataPoint has a numerical index, a type (boolean/string/etc) and a value. Clients can send DataPoints to
the device to change settings or perform functionality. In turn, the device can report state and settings by sending DataPoints to the client.

For example, sending DataPoint 6 to a simple smart lock will unlock the lock. In turn, the lock will report its unlock status by sending DataPoint 47 as a boolean back 
to the client.

## How to Use?

You can create a `TuyaBLEDevice` or a subclass, like `TuyaBLESimpleLock` using one of the two dedicated constructors:

- `TuyaBLEDevice(TuyaBLEAdvertisedDeviceInfo, TuyaDeviceCredentials)` if you are scanning devices
- `TuyaBLEDevice(NimBLEAddress, TuyaDeviceCredentials)` if you know the address of the device

In both cases, you need to provide credentials.

### TuyaDeviceCredentials

When Tuya devices are registered in one of their apps, they get a `deviceId`, `localKey` and `uuid`. Extracting the `localKey` and `deviceId` can be done thru the Tuya Cloud API, search the internet for more information. Once you have these pieces of information, you need to pass them to the `TuyaBLEDevice` on creation, since those values are used to encrypt the communication.

### Scanning

You can discover existing Tuya BLE devices by actively scanning for BLE advertisements. Use `TuyaBLEAdvertisedDeviceInfo::fromBLEAdvertisedDevice()` to check if a `NimBLEAdvertisedDevice` is a Tuya device and what its `uuid` is: this function will return an invalid info object if the device is not a Tuya device and a valid `TuyaBLEAdvertisedDeviceInfo` class if it is.

Example of scanning devices:
```c++
NimBLEScan *pBLEScan;
std::shared_ptr<TuyaBLEDevice> _tuyaBleDevice;
class MyAdvertisedDeviceCallbacks : public NimBLEScanCallbacks {
    void onResult(NimBLEAdvertisedDevice *advertisedDevice) {
      auto info = TuyaBLEAdvertisedDeviceInfo::fromBLEAdvertisedDevice(*advertisedDevice);
      if(info.isValid()) {
        Serial.println(advertisedDevice->getAddress().toString().c_str());
        Serial.println(info.uuid());

_tuyaBleDevice = std::make_shared<TuyaBLEDevice>(info, credentials);
        // you cannot connect here, because you are still scanning:
        // stop scanning and connect to the device in the next loop()
      }
    }
};

void startScan() {
  NimBLEScan* scan = NimBLEDevice::getScan();
  pBLEScan = scan;
  scan->setActiveScan(true);
  scan->setScanCallbacks(new MyAdvertisedDeviceCallbacks());
  scan->start(0, true);
}
```

### Connecting and Callbacks

To communicate with the tuya device, you first need to connect. This kicks of a key-exchange between the device and client to establish a session. When the device is ready for communication, the `isReady()` function returns `true`. Use `device.setOnReadyCallback()` to get notified when the device is ready. When the device is ready, you can ask for datapoint updates and send datapoints.

### DataPoints

Use `TuyaBLEDevice.requestDataPointsUpdate()` to ask the device for data points. DataPoints can be send back to the client in multiple batches. For each datapoint, the `onReceivedDataPointCallback` is called with the DataPoint that got updated. Use the `onUpdatedReportedDataPointsCallback` to get notified when a batch of DataPoint has been received.

You can read DataPoints received by the device using the `reportedDataPoints()`, `reportedDataPoint(uint8_t)` or one of the dedicated helpers, such as `reportedBooleanDataPoint(uint8_t, defaultValue)`. A DataPoint is of type `TuyaDataPoint`, which has methods for reading the id, type and value.

Sending datapoints is done using the `sendDataPoints()` method, this method takes a vector of `TuyaDataPoint`s and an optional callback that will be invoked when the device reports that it sucessfully received the datapoint. You can quickly create Datapoints using the factory methods, such as `TuyaDataPoint::boolean(9, true)`.

## Example

This example connects to a simple tuya BLE smart lock
```c++
#include <Arduino.h>
#include <NimBLEDevice.h>
#include "TuyaBLEDevice.h"
#include "TuyaBLESimpleLock.h"

auto credentials = TuyaDeviceCredentials("<uuid>", "<id>", "<localKey>");
auto mac = NimBLEAddress("aa:bb:cc:dd:ee:ff"); // mac address of the device

std::shared_ptr<TuyaBLESimpleLock> lock;

void setup() {
  Serial.begin(115200);
  while(!Serial);

// initialize bluetooth
  NimBLEDevice::init("");

// create our lock by address
  lock = std::make_shared<TuyaBLESimpleLock>(mac, credentials);

// enable debug output
  lock->enableDebugLog();

// register a callback for when the device is ready for communication
  lock->setOnReadyCallback([](TuyaBLEDevice* device) {
    // when ready, request datapoints from the device
    device->requestDataPointsUpdate();

// also send an unlock command to the device for memberId=1
    Serial.println("READY, sending unlock!");
    lock->shortRangeUnlock(1, [](TuyaBLEDevice* device) {
      // when the device has received the unlock command, disconnect our BLE connection
      Serial.println("unlocked, disconnecting");
      device->disconnect();
    });
  });

// print received datapoints
  lock->setOnReceivedDataPointCallback([](TuyaBLEDevice* device, const TuyaDataPoint& dp) {
    Serial.println("dp: " + dp.debugDescription());
  });

// and connect once everything is set up
  lock->connect();
}

```

ESP-TuyaBLE

ESP-TuyaBLE Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

ESP-TuyaBLE

ESP-TuyaBLE Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README