Bluetooth serial
What this example shows
Exchange text between a phone and Inkplate 7SPECTRA over Bluetooth LE. What the phone sends appears in the Serial Monitor; what you type in the Serial Monitor is sent to the phone. The screen shows a short message once Bluetooth has started.
Pair the Inkplate with your phone in the phone's Bluetooth settings, then open a Bluetooth serial terminal app (the sketch's comments name Serial Bluetooth Terminal; a similar app works too) and pick the Inkplate from its device list.
This example also uses the Bluetooth LE library (BLEDevice, BLEServer, BLEUtils, BLE2902) from arduino-esp32, which is not part of the Inkplate library and comes with the ESP32 board package.
Example code
#include <BLEDevice.h>
#include <BLEServer.h>
#include <BLEUtils.h>
#include <BLE2902.h>
#include "Inkplate.h"
#define SERVICE_UUID "6E400001-B5A3-F393-E0A9-E50E24DCCA9E" // UART service UUID
#define CHARACTERISTIC_UUID_RX "6E400002-B5A3-F393-E0A9-E50E24DCCA9E" // For data coming IN to Inkplate
#define CHARACTERISTIC_UUID_TX "6E400003-B5A3-F393-E0A9-E50E24DCCA9E" // For data coming OUT from Inkplate
Inkplate inkplate; // Create an object on Inkplate library and also set library into 1-bit mode (BW)
BLEServer *pServer = NULL; // Pointer to BLEServer
BLECharacteristic *pTxCharacteristic; // Pointer to TX characteristic
bool deviceConnected = false; // Is client currently connected
bool oldDeviceConnected = false; // Store the previous connection
class MyServerCallbacks : public BLEServerCallbacks {
void onConnect(BLEServer *pServer)
{
deviceConnected = true;
Serial.println("Device connected");
};
void onDisconnect(BLEServer *pServer)
{
deviceConnected = false;
Serial.println("Device disconnected");
}
};
class MyCallbacks : public BLECharacteristicCallbacks
{
void onWrite(BLECharacteristic *pCharacteristic)
{
String rxValue = pCharacteristic->getValue();
if (rxValue.length() > 0)
{
Serial.print("Received Value: ");
for (int i = 0; i < rxValue.length(); i++)
{
Serial.print(rxValue[i]);
}
Serial.println();
}
}
};
void setup()
{
inkplate.begin(); // Init Inkplate library (you should call this function ONLY ONCE)
inkplate.clearDisplay(); // Clear frame buffer of display
inkplate.setTextSize(3); // Scale text to be 3 times bigger then original (5x7 px)
inkplate.setTextColor(INKPLATE_BLACK);
inkplate.println("Bluetooth Serial");
inkplate.println("Example");
inkplate.println();
inkplate.setTextSize(2);
Serial.begin(115200);
BLEDevice::init("Inkplate 7SPECTRA");
pServer = BLEDevice::createServer();
pServer->setCallbacks(new MyServerCallbacks());
BLEService *pService = pServer->createService(SERVICE_UUID);
pTxCharacteristic = pService->createCharacteristic(CHARACTERISTIC_UUID_TX, BLECharacteristic::PROPERTY_NOTIFY);
pTxCharacteristic->addDescriptor(new BLE2902());
BLECharacteristic *pRxCharacteristic = pService->createCharacteristic(CHARACTERISTIC_UUID_RX, BLECharacteristic::PROPERTY_WRITE);
pRxCharacteristic->setCallbacks(new MyCallbacks());
pService->start();
pServer->getAdvertising()->start();
if (esp_bt_controller_get_status() != ESP_BT_CONTROLLER_STATUS_ENABLED)
{
Serial.println("BLE controller failed to start");
inkplate.println("BLE FAILED");
}
else
{
inkplate.println("The device started, now you can ");
inkplate.println("pair it with Bluetooth and send");
inkplate.println("messages.");
inkplate.println();
inkplate.println("Open Serial Monitor at 115200");
inkplate.println("baud!");
}
inkplate.display();
}
void loop()
{
if (deviceConnected)
{
if (Serial.available())
{
String s = Serial.readStringUntil('\n') + "\n"; // Load the message from serial
Serial.printf("Sent value: %s\n", s.c_str());
pTxCharacteristic->setValue((uint8_t *)s.c_str(), strlen(s.c_str())); // Convert the message into bytes
pTxCharacteristic->notify(); // Transmit the message
}
}
if (!deviceConnected && oldDeviceConnected)
{
delay(500); // Allow bluetooth stack some time
pServer->startAdvertising(); // Restart advertising
oldDeviceConnected = false; // Update state
}
if (deviceConnected && !oldDeviceConnected)
{
oldDeviceConnected = true; // Update the old state
}
}
The comment next to Inkplate inkplate; mentions a 1-bit mode; Inkplate 7SPECTRA has only its six-color mode, and the constructor takes no mode.
Functions used
Inkplate()returns NoneCreates the Inkplate object. Inkplate 7SPECTRA has a single six-color mode, so the constructor takes no mode argument.
ReturnsConstructor; no return value.
inkplate.begin()returns voidInitializes the library, the peripherals and the frame buffer. Call it once in setup().
ReturnsNothing.
inkplate.clearDisplay()returns voidFills the frame buffer with white. It does not change the panel.
ReturnsNothing.
inkplate.setTextSize(uint8_t s)returns voidSets the text magnification: 3 for the title, 2 for the lines after it.
ReturnsNothing.
inkplate.setTextColor(uint16_t c)returns voidSets the text color, here INKPLATE_BLACK.
ReturnsNothing.
inkplate.println(text)returns size_tPrints text into the frame buffer and moves to the next line, like Serial.println().
ReturnsNumber of bytes printed.
inkplate.display(bool _leaveOn = 0)returns voidSends the whole frame buffer to the panel and refreshes it.
ReturnsNothing.
Serial.begin(115200)returns voidArduino core function: starts the serial port at 115200 baud.
ReturnsNothing.
BLEDevice::init(name)returns voidBluetooth LE library of the ESP32 board package: starts Bluetooth LE with the device name the phone sees, here Inkplate 7SPECTRA.
ReturnsNothing.
BLEDevice::createServer()returns BLEServer *Bluetooth LE library: creates the Bluetooth LE server.
ReturnsThe server.
pServer->setCallbacks(callbacks)returns voidBluetooth LE library: registers the object whose onConnect and onDisconnect functions run when a phone connects or disconnects.
ReturnsNothing.
pServer->createService(SERVICE_UUID)returns BLEService *Bluetooth LE library: creates the service with the UART service UUID defined at the top of the sketch.
ReturnsThe service.
pService->createCharacteristic(uuid, properties)returns BLECharacteristic *Bluetooth LE library: creates a characteristic. The sketch makes a transmit characteristic with PROPERTY_NOTIFY (data going out from Inkplate) and a receive characteristic with PROPERTY_WRITE (data coming in).
ReturnsThe characteristic.
pTxCharacteristic->addDescriptor(new BLE2902())returns voidBluetooth LE library: lets the phone turn notifications on and off for the transmit characteristic.
ReturnsNothing.
pRxCharacteristic->setCallbacks(new MyCallbacks())returns voidBluetooth LE library: registers the object whose onWrite function runs when the phone writes to the receive characteristic.
ReturnsNothing.
pCharacteristic->getValue()returns StringBluetooth LE library: returns the text the phone wrote. The sketch prints it to the Serial Monitor character by character.
ReturnsThe received text.
pService->start()returns voidBluetooth LE library: starts the service.
ReturnsNothing.
pServer->getAdvertising()->start()returns voidBluetooth LE library: starts advertising, so the phone can find the Inkplate.
ReturnsNothing.
pServer->startAdvertising()returns voidBluetooth LE library: restarts advertising. The sketch calls it in loop() half a second after a phone disconnects, so a new one can connect.
ReturnsNothing.
esp_bt_controller_get_status()returns esp_bt_controller_status_tESP32 board package function: returns the state of the Bluetooth controller. The sketch compares it with ESP_BT_CONTROLLER_STATUS_ENABLED to report whether Bluetooth started.
ReturnsThe controller state.
pTxCharacteristic->setValue(uint8_t *data, size_t length)returns voidBluetooth LE library: sets the bytes to send to the phone; the sketch passes the line read from the Serial Monitor.
ReturnsNothing.
pTxCharacteristic->notify()returns voidBluetooth LE library: sends the value to the connected phone.
ReturnsNothing.
Serial.available()returns intArduino core function: returns how many bytes wait in the serial receive buffer.
ReturnsNumber of bytes available.
Serial.readStringUntil(char terminator)returns StringArduino core function: reads characters from the serial port until the terminator, here a newline.
ReturnsThe text read.
Serial.print(value)returns size_tArduino core function: prints text to the Serial Monitor without a line break.
ReturnsNumber of bytes printed.
Serial.println(text)returns size_tArduino core function: prints a line to the Serial Monitor.
ReturnsNumber of bytes printed.
Serial.printf(format, ...)returns size_tArduino core function on ESP32: prints formatted text to the Serial Monitor.
ReturnsNumber of bytes printed.
delay(ms)returns voidArduino core function: waits for the given number of milliseconds.
ReturnsNothing.
What to expect
The screen shows Bluetooth Serial Example followed by the message The device started, now you can pair it with Bluetooth and send messages. and a hint to open the Serial Monitor at 115200 baud. If Bluetooth does not start, it shows BLE FAILED instead.
When a phone connects and sends text, the Serial Monitor at 115200 baud shows it, for example after the phone sends hello:
Device connected
Received Value: hello
Type a line in the Serial Monitor while the phone is connected and the sketch prints Sent value: followed by your text and sends it to the phone. The sketch prints Device disconnected when the phone leaves.
🔗Open the complete example
examples/Inkplate7SPECTRA/Advanced/Communications/Inkplate7SPECTRA_Bluetooth_Serial