Loading...
Searching...
No Matches
README

# Bind: C++ UI Toolkit for Arduino

Bind is a C++ UI library for Arduino, allowing developers to create interactive user interfaces for their Arduino projects. Bind allows you to display data using text, charts, gauges, street maps, and many more, and also capture user inputs through an array of interactive elements such as buttons, checkboxes, joysticks, sliders, and color pickers. You can check out the complete class documentation here.

Get BindCanvas Android App:

A short YouTube video introducing Bind:

What is Bind?

| Sample app created by Bind| Sample app created by Bind| |:—:|:—:|

## Installation:

To install Bind in your Arduino IDE, use the Library Manager (available from IDE version 1.6.2). Open the IDE, go to Tools > Manage Libraries..., search for **_Bind_**, click install, and wait for completion. Once installed, you'll see an 'Installed' tag next to the Bind library. Close the Library Manager

What is Bind?

Now you can find the library examples under File > Examples > Bind

## Usage

Using Bind is easy, requiring just three fundamental functions: `init`, `join`, and `sync`. First, use `init` to initialize the Bind interface. Then, employ `join` to associate objects with callbacks for interactive elements. Lastly, use `sync` to synchronize with the screen and receive events.

No need to delve into data parsing or protocol handling, everything is internally managed by the Bind library. Simply define your objects, set attributes like location, size, and color, and call `bind.sync(myBindObject)` to display them on the screen.

For interactive elements like buttons or color pickers where you expect user input in your C++ code, set a callback function using their `setCallback` function, for example for buttons we can do this like:

.setCallback(myButtonClicked)

In this context,`myButtonClicked` is a function like:

void myButtonClicked() {
// Your custom logic when the button is clicked
}

This callback function allows you to seamlessly integrate your own logic with the user interactions, defining specific actions to be executed when the associated button is clicked. This simplifies the process, allowing you to focus on defining your UI elements and their behavior. Check the library documentation or examples (under File > Examples > Bind) for more information.

## UI Elements

UI element | Description | Documents | Example
--- | --- | --- | ---
| The BindButton class represents a button UI element | BindButton | Button.ino
| Represents a toggle switch UI element | BindSwitch | Switch.ino
| Represents a SeekBar object | BindSeekBar | Seekbar.ino
| Represents a knob UI element | BindKnob | DialKnob.ino
| Represents a chart UI element | BindChart | Chart.ino
| Represents a color picker UI element | BindColorPicker | ColorPicker.ino
| Represents a gauge UI element | BindGauge | Gauges.ino
| Represents a compact gauge UI element | BindGaugeCompact | Gauges.ino
| Represents a simple gauge UI element | BindGaugeSimple | Gauges.ino
| Represents a heading gauge UI element | BindHeadingIndicator | FlightIndicators.ino
| Represents a roll pitch gauge UI element | BindAttitudeIndicator | FlightIndicators.ino
| Represents a joystick UI element | BindJoystick | Joystick.ino
| Represents a street map UI element | BindMap | StreetMap.ino
| Represents a terminal log UI element | BindTerminal | Terminal.ino
| Represents a text input UI element | BindTextInput | TextInput.ino
| Represents a text label UI element | BindTextLabel | TextLabel.ino
| Represents a panel UI element | BindRectangle | DrawBox.ino
| A customizable dialog box | BindDialog | Dialog.ino
Screen Configs | Configuration settings for a BindCanvas application screen. | BindCanvasSettings | ScreenConfigs.ino

## Compatibility

- Communication Methods: Bind currently supports Bluetooth (Classic and BLE), Wifi , and Serial port (over USB) for communication. Support for IoT (MQTT) interfaces will be integrated soon.
- Hardware Support:

Board | USB | Bluetooth dongle (HC-06, HM-10, or similar) | Built-in Bluetooth | Wifi | Note
--- | --- | --- | --- | --- | ---
Avr Arduino (Uno, Pro Micro,...) | :heavy_check_mark: | :heavy_check_mark: | N/A | N/A | Works OK but has a very limited RAM.
ESP32 | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | Board of choice. Use The Arduino ESP32 v3.0.1 or higher
Raspberry Pi Pico W / Pico2 W | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | Works great with Wifi but Pico's Bluetooth driver is not perfect yet. Use arduino-pico v4.5.4 or higher
ESP8266 | :heavy_check_mark: | :heavy_check_mark: | N/A | :heavy_check_mark: |
Other Boards | :heavy_check_mark: | :heavy_check_mark: | N/A | TBD | USB serial port and external Bluetooth dongle should work with all boards.

- Android Compatibility: Designed for Android 6 Marshmallow and later versions (API Level 23+), ensuring compatibility with a broad range of new devices and most of still-alive aging Android devices.
- Screen Size: Bind supports all screen sizes, from compact phones to larger tablets. Additionally, your Arduino code receives notifications about the screen size when users connect, allowing you to dynamically configure element positions and sizes to suit various display dimensions.

## Getting Started

Installation: Include the Bind library in your Arduino IDE and install the BindCanvas app from google play on your phone to get started.

## Example Usage 1 (Using Serial port over USB for all boards)

#include "Bind.h"
Bind bind;
BindButton myButton;
const int ledPin = 2;
bool led_is_on = false;
void setup() {
pinMode(ledPin, OUTPUT);
// Initialize the Bind object and specify the communication method (Serial) and callback function (onConnection).
bind.init(Serial, onConnection);
}
void onConnection(int16_t width, int16_t height) {
addButton();
}
void addButton() {
// Set the Button's position on the screen.
myButton.x = 30;
myButton.y = 150;
myButton.setLabel("Toggle LED");
myButton.cmdId = BIND_ADD_OR_REFRESH_CMD;
// Setting the click callback
myButton.setCallback(myButtonClicked);
// Synchronize the myButton object with BindCanvas.
bind.sync(myButton);
}
void myButtonClicked() {
// Your custom logic when the button is clicked
// For example toggle a LED:
led_is_on = !led_is_on;
digitalWrite(ledPin, led_is_on);
}
void loop() {
// Regularly synchronize Bind UI events
bind.sync();
// Other loop logic
}
BindButton
The BindButton class represents a button UI element for use with BindCanvas.
Definition BindButton.hpp:27
BindButton::x
int16_t x
X-coordinate position of the button.
Definition BindButton.hpp:50
BindButton::y
int16_t y
Y-coordinate position of the button.
Definition BindButton.hpp:51
BindButton::cmdId
uint8_t cmdId
Command ID for the button. See the notes for possible cmdId values.
Definition BindButton.hpp:52
BindButton::setLabel
void setLabel(const char *cstr)
Sets the callback function for the button.
Definition BindButton.hpp:72
BindButton::setCallback
void setCallback(void(*callback)(void))
Set the press callback function for the button.
Definition BindButton.hpp:89
Bind
The Bind class provides a framework for creating interactive applications with BindCanvas.
Definition Bind.h:62
Bind::sync
void sync(BindView &obj)
Synchronizes a BindView object with the BindCanvas screen. Same as sync(BindView *obj) but uses the o...
Definition Bind.cpp:74
Bind::init
bool init(Stream &stream, void(&setupCallback)(int16_t, int16_t))
Initializes the Bind framework with communication and screen setup.
Definition Bind.cpp:23

## Example Usage 2 (Using Bluetooth for ESP32)

#include "Bind.h"
#include "BindUtil/BindOverBLE.h"
Bind bind;
BleStream bleStream;
BindButton myButton;
const int ledPin = 2;
bool led_is_on = false;
void setup() {
pinMode(ledPin, OUTPUT);
//Initialize the BLE device:
bleStream.begin("YOUR_DEVICE_NAME", bind);
// Initialize the Bind object and specify the communication method (Serial) and callback function (onConnection).
bind.init(bleStream, onConnection);
}
void onConnection(int16_t width, int16_t height) {
addButton();
}
void addButton() {
// Set the Button's position on the screen.
myButton.x = 30;
myButton.y = 150;
myButton.setLabel("Toggle LED");
myButton.cmdId = BIND_ADD_OR_REFRESH_CMD;
// Setting the click callback
myButton.setCallback(myButtonClicked);
// Synchronize the myButton object with BindCanvas.
bind.sync(myButton);
}
void myButtonClicked() {
// Your custom logic when the button is clicked
// For example toggle a LED:
led_is_on = !led_is_on;
digitalWrite(ledPin, led_is_on);
}
void loop() {
//Do something here
}

#### Browse the example folder for more sample.

## Contribution

- Contributions are welcome! If you have ideas or improvements, feel free to open an issue or submit a pull request.