nomi-nonsz/lunar-vein-arduino
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update API docs

Browse Source
This commit is contained in:
Nomi Nonsense (Nonszy) 2024-03-06 10:09:14 +07:00
parent 737a2e2fd3
commit 76e9ae14e5
4 changed files with 289 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

219
README.md
View File

@ -1,28 +1,225 @@
# Lunar Vein: Arduino
A REST API based serial communication, assisted Firmata protocol and johnny-five API, enabling software communication with the Arduino board using the Server API., that's it. Idk about electronics and networking actually. But that piece of knowledge motivated me to interact it with other software. Enjoy (⁠づ⁠￣⁠ ⁠³⁠￣⁠)⁠づ
A **SIMPLE** REST API based serial communication. Assisted Firmata protocol and johnny-five API, enabling software communication with the Arduino board using the Server API. that's it. Idk about electronics and networking actually. But that piece of knowledge motivated me to make some IoT stuff. Enjoy (⁠づ⁠￣⁠ ⁠³⁠￣⁠)⁠づ
## Setup
Tools that are required
- Arduino Board
- [Arduino IDE](https://www.arduino.cc/en/software)
- [Node.js](https://nodejs.org/en) v16.0.0^ or other javascript runtime
### Board
Arduino assembly guide also available in [johnny-five](https://github.com/rwaldron/johnny-five?tab=readme-ov-file#setup-and-assemble-arduino) documentation
1. Download [Arduino IDE](https://www.arduino.cc/en/software)
2. Plug in your Board via USB
3. Open Arduino IDE then select your Board
4. Go to `File > Examples > Firmata` Select `StandarFirmataPlus`
5. Upload the sketch
Arduino assembly guide also available in [johnny-five](https://github.com/rwaldron/johnny-five?tab=readme-ov-file#setup-and-assemble-arduino) documentation\
1. Plug in your Board via USB
2. Open Arduino IDE then select your Board
3. Go to `File > Examples > Firmata` Select `StandarFirmataPlus`
4. Upload the sketch
### Server
1. Clone project and Install
```bash
> git clone https://github.com/norman-andrians/lunar-vein-arduino.git && cd lunar-vein-arduino
> npm i
git clone https://github.com/norman-andrians/lunar-vein-arduino.git && cd lunar-vein-arduino
npm i
```
2. Add `.env` file in the project root directory with the `SERIAL_PORT` variable
```
SERIAL_PORT=/dev/ttyUSB0
```
3. Run the project
```bash
> npm start
```
npm start
```
#### Other scripts
- You can see what ports are connected to the device by running `npm run ports` script.
```bash
npm run ports
```
```
> lunar-vein-arduino@1.0.0 ports
> ts-node src/ports/print.ts
3 Ports available
1. /dev/ttyUSB0
2. /dev/ttyUSB1
3. /dev/ttyACM0
```
# API Documentation
## Table of contents
- [Common HTTP Responses](#common-http-responses)
- [JSON Response](#json-response)
- [Example Request](#example-request)
- [PIN](#pin)
- [Read pin mode](#read-pin-mode)
- [Set pin mode](#set-pin-mode)
- [LED](#led)
- [Read led state](#read-led-state)
- [Set led state](#set-led-state)
## Common HTTP Responses
Some HTTP responses are sent with JSON, otherwise an HTML body will be sent which is the default express.js response
| HTTP Status | Marks |
|-------------|-------|
| 200 | The request `act` was successful |
| 400 | You may be making an invalid request, try to check the payload or recheck the documentation. |
| 404 | The resource wass not found |
| 405 | Method not allowed, servers usually only accept `GET` and `PATCH` methods |
| 500 | An error in the app server, if it continues please raise an issue or ask to contribute. |
## JSON Response
```json
{
"status": 200,
"pin_state": {
"13": "HIGH"
},
"message": "Pin 13 Set to HIGH"
}
```
| Property | Description |
|----------|-------------|
| status | HTTP Status code |
| pin_state | The state value of the pin that has been changed |
| message | Descriptive message of the changed state |
## Example Request
This is an example of javascript code sending a request to turn on the LED light, [See LED API](#set-led-state)
```javascript
async function turnOnLed() {
const res = await fetch("http://localhost:3000/led/13/on"); // Set LED to HIGH
const data = await res.json();
console.log(data);
}
```
## PIN
### Read pin mode
- **URL Endpoint**
/pin/:p/
- **URL Params**
| Params | Mark | Type | Required | Description |
|--------|------|------|----------|-------------|
| p | pin | `string` | true | Seleced pin |
- **Method**
`GET`
- **Sample Response**
```json
{
"status": 200,
"pins": [
{
"pin": 13,
"mode": "OUTPUT"
}
],
"message": "Pin 13 is OUTPUT"
}
```
### Set pin mode
- **URL Endpoint**
/pin/:p/:m
- **URL Params**
| Params | Mark | Type | Required | Description |
|--------|------|------|----------|-------------|
| p | pin | `string` | true | Seleced pin |
| m | mode | `'input'`, `'output'`, `'servo'` | true | Pin Mode |
- **Method(s)**
`PATCH`
- **Sample Response**
```json
{
"status": 200,
"pins": [
{
"pin": 13,
"mode": "OUTPUT"
}
],
"message": "Pin 13 setted as OUTPUT"
}
```
## LED
### Read led state
- **URL Endpoint**
/led/:p/
- **URL Params**
| Params | Mark | Type | Required | Description |
|--------|------|------|----------|-------------|
| p | pin | `string` | true | Seleced pin |
- **Method**
`GET`
- **Sample Response**
```json
{
"status": 200,
"pin_state": {
"13": "HIGH"
},
"message": "Led pin 13 is HIGH"
}
```
### Set led state
- **URL Endpoint**
/pin/:p/:a
- **URL Params**
| Params | Mark | Type | Required | Description |
|--------|------|------|----------|-------------|
| p | pin | `string` | true | Seleced pin |
| a | act | `'on'`, `'off'` | true | Action |
- **Method(s)**
`PATCH`
- **Sample Response**
```json
{
"status": 200,
"pin_state": {
"13": "HIGH"
},
"message": "Led pin 13 setted HIGH"
}
```

112
src/controller/led.ts
View File

@ -4,21 +4,30 @@ import { ChannelPins, digitalValue, voltage } from ".";
import { Led } from "johnny-five";
export async function readLed (req: Request, res: Response) {
const { p } = req.params;
const pin: number = Number.parseInt(p);
const pinState: digitalValue = board.pins[pin].value == 1 ? 'ON' : 'OFF';
return res.status(200).json({
status: 200,
pin_state: {
[pin]: pinState
}
});
export function readLed (req: Request, res: Response): Response<string | any> {
try {
const { p } = req.params;
const pin: number = Number.parseInt(p);
const pinState: digitalValue = board.pins[pin].value == 1 ? 'ON' : 'OFF';
return res.status(200).json({
status: 200,
pin_state: {
[pin]: pinState
}
});
}
catch (err) {
console.error(err);
return res.status(500).json({
status: 200,
message: "Internal server error"
})
}
}
export async function writeLed (req: Request, res: Response) {
export function writeLed (req: Request, res: Response): Response<string | any> {
const { p, a } = req.params;
const act: string = a.toLocaleLowerCase();
const pin: number = Number.parseInt(p);
@ -63,47 +72,56 @@ export async function writeLed (req: Request, res: Response) {
};
export async function readRgbLed (req: Request, res: Response) {
export function readRgbLed (req: Request, res: Response): Response<string | any> {
const r: number = Number.parseInt(req.body.r);
const g: number = Number.parseInt(req.body.g);
const b: number = Number.parseInt(req.body.b);
const rgbPins: number[] = Object.values({ r, g, b });
try {
const rgbPins: number[] = Object.values({ r, g, b });
for (let i = 0; i < rgbPins.length; i++) {
const pin = rgbPins[i];
if (Number.isNaN(pin)) {
return res.status(400).json({
status: 400,
message: `Invalid pin ${pin} param, it should be integer`
});
for (let i = 0; i < rgbPins.length; i++) {
const pin = rgbPins[i];
if (Number.isNaN(pin)) {
return res.status(400).json({
status: 400,
message: `Invalid pin ${pin} param, it should be integer`
});
}
}
const led = new Led.RGB({
pins: {
red: r,
green: g,
blue: b
},
isAnode: true
})
led.red = new Led(r);
led.green = new Led(g);
led.blue = new Led(b);
return res.status(200).json({
status: 200,
pin_state: {
[r]: led.red.isOn,
[g]: led.green.isOn,
[b]: led.blue.isOn
}
});
}
catch (err) {
console.error(err);
return res.status(500).json({
status: 200,
message: "Internal server error"
})
}
const led = new Led.RGB({
pins: {
red: r,
green: g,
blue: b
},
isAnode: true
})
led.red = new Led(r);
led.green = new Led(g);
led.blue = new Led(b);
return res.status(200).json({
status: 200,
pin_state: {
[r]: led.red.isOn,
[g]: led.green.isOn,
[b]: led.blue.isOn
}
});
}
export async function writeRgbLed (req: Request, res: Response) {
export function writeRgbLed (req: Request, res: Response): Response<string | any> {
const r: ChannelPins = req.body.r;
const g: ChannelPins = req.body.g;
const b: ChannelPins = req.body.b;
@ -140,14 +158,14 @@ export async function writeRgbLed (req: Request, res: Response) {
const pins: string = rgbLeds.map(c => c.pin.toString()).join(", ");
const values: string = rgbLeds.map(c => `${c.value}`).join(", ");
res.status(200).json({
return res.status(200).json({
status: 200,
message: `Success changed pins ${pins} to state ${values}`
});
}
catch (err) {
console.error(err);
res.status(500).json({
return res.status(500).json({
status: 500,
message: "Internal Server Error"
});

15
src/controller/pin.ts
View File

@ -10,9 +10,12 @@ export function readPin (req: Request, res: Response) {
return res.status(200).json({
status: 200,
state: {
used: true
},
pins: [
{
pin: pin,
mode: mode
}
],
message: `Pin ${pin} is ${mode}`
});
}
@ -28,6 +31,12 @@ export function setPin (req: Request, res: Response) {
return res.status(200).json({
status: 200,
pins: [
{
pin: pin,
mode: mode
}
],
message: `Pin ${pin} setted as ${mode}`
});
}

9
src/index.ts
View File

@ -8,19 +8,18 @@ import { board, suBoard, comport } from './setup';
import { isBoardConnected } from './middleware/connection';
import view from './routes/view';
import api from './routes/api';
import { selectPort } from './ports';
import socketHandler from './handlers/socketHandler';
const app = express();
const server = http.createServer(app);
const io = new Server(server, {
const server: http.Server = http.createServer(app);
const io: Server = new Server(server, {
cors: {
origin: "*"
}
}); // I have no experience at WebSocket, so.. forgive me :)
const host = 'localhost';
const port = 3000;
const host: string = 'localhost';
const port: number = 3000;
app.use(express.json());
app.use(express.static('client'));