https://github.com/takeyamayuki/restuino

A library, firmware to handle arduino GPIO via REST API.
https://github.com/takeyamayuki/restuino

arduino bootloader cpp esp32 esp8266 http iot iot-platform platformio rest-api

Last synced: 5 months ago
JSON representation

A library, firmware to handle arduino GPIO via REST API.

Host: GitHub
URL: https://github.com/takeyamayuki/restuino
Owner: takeyamayuki
License: apache-2.0
Created: 2022-07-29T12:23:11.000Z (over 3 years ago)
Default Branch: main
Last Pushed: 2023-07-06T02:58:52.000Z (over 2 years ago)
Last Synced: 2025-06-13T21:09:15.409Z (6 months ago)
Topics: arduino, bootloader, cpp, esp32, esp8266, http, iot, iot-platform, platformio, rest-api
Language: C++
Homepage: https://zenn.dev/ninzin/articles/5c859a0bfc1ee6
Size: 82 KB
Stars: 17
Watchers: 2
Forks: 2
Open Issues: 1
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

RESTuino

A library, firmware to handle arduino GPIO via REST API / arduino wrapper with REST API

# Contents

- [What is RESTuino?](#what-is-restuino)
- [Requirements](#requirements)
- [Installation](#installation)
- [Usage](#usage)
- [Control GPIO](#control-gpio)
- [Control of the entire system](#control-of-the-entire-system)
- [Examples](#examples)
- [curl](#curl)
- [Python](#python)
- [homebridge](#homebridge)
- [Talend API Tester](#talend-api-tester)

# What is RESTuino?

In embedded development, we have `Arduino` and `CircuitPython` as software initiatives to improve development productivity. Today, a new standard in embedded development is born.
It is the `RESTuino`, interactive embedded development firmware for ESP32.

I created an external API layer for the hardware abstraction layer to enable GPIO operations from outside the microcontroller.
In this case, I created `RESTful API` for the `Arduino` hardware abstraction layer inside the `ESP32` microcontroller to enable GPIO operations.

Specifically, you can specify a GPIO number in the URL, `POST` to define a pin state (digitalWrite, digitalRead, etc.), `PUT` to update the value (digitalWrite to HIGH, LOW, etc.), `GET` to get current information, `DELETE` to disable a pin state. And if you do `save`, the pin state is saved in EEPROM, so it is easy to operate as client-side software in IoT.

🌱 `RESTuino` makes it possible to communicate *system functions & data* in the IoT.

✨ `RESTuino` allows us to make...
- `IoT client` Arduino GPIOs can be manipulated via REST API.
- `Interactive Microcomputer Programming` via [curl](https://github.com/curl/curl), [Talend API Tester](https://chrome.google.com/webstore/detail/talend-api-tester-free-ed/aejoelaoggembcahagimdiliamlcdmfm?hl=ja) or similer.

✍ `RESTuino` can be operated with...
- [curl](https://github.com/curl/curl)
- [Homebridge](https://github.com/homebridge/homebridge)
- [Python(requests)](https://requests.readthedocs.io/en/latest/)
- [Talend API Tester](https://chrome.google.com/webstore/detail/talend-api-tester-free-ed/aejoelaoggembcahagimdiliamlcdmfm?hl=ja)
or similer.

# Requirements
- ESP32-based board

The tested boards are as follows. Other products can also be used if they are equipped with esp32.
- [ESP32 DevKitC](https://www.espressif.com/en/products/devkits/esp32-devkitc)
- [MH ET LIVE ESP32DevKIT](https://ja.aliexpress.com/item/32880702799.html?spm=a2g0s.8937460.0.0.72832e0edJMMVm&gatewayAdapt=glo2jpn)

- PlatformIO or Arduino IDE

# Installation

See [PlatformIO example](/examples/esp32_platformio/), [Arduino IDE example](/examples/esp32_basic/esp32_basic.ino)

You can install the library in two ways.
- [PlatformIO](https://registry.platformio.org/libraries/takeyamayuki/RESTuino)
- [Arduino IDE](https://reference.arduino.cc/reference/en/libraries/restuino/)

1. Clone this repository.
```sh
$ git clone https://github.com/takeyamayuki/RESTuino.git
```
2. Open the `esp32_platformio` example in PlatformIO or `esp32_basic` example in Arduino IDE.

1. Define `ssid`, `password` of your wifi router by changing `ssid_def`, `ssid_pass`. If more than one RESTuino is to be installed, change `host_name`. `serial_baud` is the baud rate of the serial monitor. `9600` is the default value.

```cpp
restuino.host_name = "restuino";
restuino.ssid_def = "YOUR_SSID";
restuino.ssid_pass = "YOUR_PASSWORD";
restuino.serial_baud = 9600;
```

4. Build and upload.
5. Clear EEPROM.

Initialize the RESTuino system when you see `WiFi connected.` on the serial monitor.

```sh
$ curl restuino.local/ -X DELETE
Change all pins to nan status...
```

6. Use this the way you want to use it.

# Usage

1. Specify the GPIO number in the URL
2. `POST` to define the pin status (digitalWrite, digitalRead, etc.)
3. `PUT` to update the value (HIGH for digitalWrite, etc.)
4. `GET` to obtain current information (digitalRead, etc.)
5. `DELETE` to disable the pin status

> **Note**
> When sending the request body, always specify `Content-Type: text/plain` as the header.

## Control GPIO

### URL

http://restuino.local/gpio(pin_number)

(pin_number) is the pin number of the GPIO. For example, `http://restuino.local/gpio15` is the GPIO15 of ESP32.
It is recommended to use `http://restuino.local` instead of accessing the IP address, because of the heavy use of `ESP.restart()` in the RESTuino process.

Specify the target GPIO pin by URL.

### POST
Use `POST` to set the status of a pin.

```sh
# e.g. digitalWrite
$ curl restuino.local/gpio15 -X POST -H 'Content-Type: text/plain' -d 'digitalWrite'
digitalWrite
```

### PUT

Use `PUT` to change or define the output value of any pin.
The following request body can be sent when the GPIO pin set by `POST` is in the following state.

- `digitalWrite`

Request body: `HIGH` | `LOW` | `0` | `1`

```sh
# e.g.
$ curl restuino.local/gpio15 -X PUT -H 'Content-Type: text/plain' -d 'LOW'
LOW
```

- `ledcWrite` (alternative to `analogWrite` in esp32)

Request body: `0~256 numbers`

```sh
# e.g.
$ curl restuino.local/gpio15 -X PUT -H 'Content-Type: text/plain' -d '100'
100
```

- `Servo`
Request body: `0~180 numbers` | `switch`

- `0~180 numbers`: a servo motor moves to the angle specified by value.
- `switch`: Each time the following command is sent, the servo motor moves back and forth between `angle` and `angle0`.

```sh
# e.g.
$ curl restuino.local/gpio15 -X PUT -H 'Content-Type: text/plain' -d '88'
88
```

### GET

Use `GET` to get the status of any pin.
The following response body is received when the pin set by `POST` is in the following state.

- `analogRead`: `0~4095 numbers`
- `digitalRead`: `0` | `1`
- `Servo`: `0~180 numbers`

```sh
# e.g. digitalRead
$ curl restuino.local/gpio1 -X GET
0
```

### DELETE

Use `DELETE` to disable any pin (actually, save the setting in EEPROM and restart).

```sh
# e.g.
$ curl restuino.local/gpio1 -X DELETE
Change the pin to nan status...
```

## Control of the entire system

### URL
- http://(IP_address)
The IP address can be obtained via serial communication or `http://restuino.local` via `GET` method (It's easy with a browser).
It is recommended to use `http://restuino.local` instead of accessing the IP address, because of the heavy use of `ESP.restart()` in the RESTuino process.

- http://restuino.local

### PUT

Request body: `save` | `load` | `reboot`

- `save`: Save the current GPIO setting status to EEPROM.
- `load`: Load GPIO settings stored in EEPROM and reflect to actual pin settings.
- `reboot`: Reboot ESP32.

> **Note**
> The `load` is done automatically at startup, but the user must `save` before turning off the power.
> When operating as an IoT client, once the pin state is saved, it will be saved in eeprom, so there is no need to `save` after that.

```sh
# e.g.
$ curl restuino.local/ -X POST -H 'Content-Type: text/plain' -d 'save'
Wrote
```

### GET

Obtain IP address and GPIO status. GPIO status is output in chunks of 40. Starting from the first left digit, GPIO0, 1,2.... and its value is defined as follows.
```sh
$ curl restuino.local/ -X GET
{
"IP address": "192.168.0.29",
"GPIO status": "2000000050000002200000000000000000000000"
}
```

| number | meaning |
| ---- | ---- |
| 0 | nan |
| 1 | digitalread |
| 2 | digitalwrite |
| 3 | analogread |
| 4 | ledcwrite |
| 5 | servo |
| 6 | (touch) |
| 7 | (dacwrite) |

e.g.
Looking at the first digit of GPIO status(GPIO0), there is a number 2, which means `digitalwrite`. Therefore, `pinMode(0,OUTPUT)` is executed internally so that `GPIO0` becomes `digitalwrite`.

### DELETE

Disable all pins (actually, save the setting in EEPROM and restart).

```sh
$ curl restuino.local/ -X DELETE
Change all pins to nan status...
```

### POST

Not defined.

# Examples

See [examples](examples/).

## Python

- [python-L-chika](examples/python-L-chika/) : Programs to turn on/off the LED connected to GPIO15 every second.

- [python-Servo-switch](examples/python-Servo-switch/) : Programs to move the servo (connected to GPIO15) to the angle defined by `angle`, `angle0` every second.

1. Run setup.py
```sh
$ python setup.py
```
Configure GPIO settings. Run it only once.

2. Run main.py
```sh
$ python main.py
```
This is the main program. Use only this program when incorporating it.

https://user-images.githubusercontent.com/22733958/189347822-e8469ee5-c92b-40f8-a5f1-4262459ac20f.mp4

The program is [here](examples/python-L-chika/).

## curl

- [curl-digitalRead](examples/curl-digitalRead): Scripts that executes `digitalRead` to GPIO15 and obtains its status.

- [curl-Servo](examples/curl-Servo): Programs to move the servo (connected to GPIO15) to 88°.

1. Run setup.sh
```sh
$ chmod +x setup.sh
$ ./setup.sh
```
Configure GPIO settings. Run it only once.

2. Run main.sh
```sh
$ chmod +x main.sh
$ ./main.sh
```
This is the main program. Use only this program when incorporating it.

https://user-images.githubusercontent.com/22733958/189353947-962c44ff-effe-4be4-992b-4562dd6cd37f.mp4

The program is [here](examples/curl-digitalRead).

## [homebridge](https://github.com/homebridge/homebridge)

[homebridge](https://github.com/homebridge/homebridge) is a lightweight NodeJS server you can run on your home network that emulates the iOS HomeKit API. This allows you to use iOS apps to control devices that do not natively support HomeKit.

In the homebridge config editor, add the following to the `accessories` section:
```json
"accessories": [
{
"accessory": "CMD",
"name": "light",
"on_cmd": "curl restuino.local/gpio15 -X PUT -H 'Content-Type: text/plain' -d '56'",
"off_cmd": "curl restuino.local/gpio15 -X PUT -H 'Content-Type: text/plain' -d '6'"
}
]
```

https://user-images.githubusercontent.com/22733958/189354008-0065546a-124d-4562-aaaa-19c268d264d2.mov

## Talend API tester

https://user-images.githubusercontent.com/22733958/189336576-649f115f-5116-4f43-890a-9500fc9b182a.mp4

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/takeyamayuki/restuino

Awesome Lists containing this project

README

RESTuino