Skip to content

Commit 4948a4d

Browse files
GuihgoGuihgo
committed
[feature] send method
1 parent 772056a commit 4948a4d

File tree

4 files changed

+281
-150
lines changed

4 files changed

+281
-150
lines changed

‎LICENSE

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
The MIT License (MIT)
22

3-
Copyright (c) 2022 Guilherme Henrique Gregorini Oliveira (Guihgo)
3+
Copyright (c) 2023 Guilherme Henrique Gregorini Oliveira (guilherme@itthink.io)
44

55
Permission is hereby granted, free of charge, to any person obtaining a copy
66
of this software and associated documentation files (the "Software"), to deal

‎README.md

Lines changed: 125 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -1,108 +1,135 @@
11
# IoT Protocol
22

3-
IoT Protocol is a protocol over TCP based on HTTP for light data traffic.
3+
IoT Protocol is a protocol over TCP based on HTTP and MQTT for lightweight data traffic.
44

5-
**Motivation**: HTTP 1.1 (*http://*) protocol uses too much data traffic for IoT context. Its request minimum size is 26 bytes (https://stackoverflow.com/a/25065027/1956719) and the HOST param is mandatory for all requests.
5+
**Motivation**:
6+
1. HTTP 1.1 (*http://*) protocol is a request-response model is well-suited for web-based applications where clients need to request resources from servers and receive responses back. It is still more commonly used and more widely known among developers. But it uses too much data traffic for IoT context. Its minimum request size is 26 bytes (https://stackoverflow.com/a/25065027/1956719) and the HOST param is mandatory for all requests.
67

7-
The IOT_PROTOCOL (*iot://*) is adapted for IoT context with light data traffic. Its request minimum size is 8 bytes withless to require HOST param for requests.
8+
2. MQTT (*mqtt://*) is a publish-subscribe messaging protocol, use lightweight data traffic. Its minimum request size is 2 bytes. But it is not stateless and does not provide a request/response pattern, so it isn't restful. MQTT is designed to be a lightweight protocol that minimizes network overhead, which can make it more challenging to handle large or complex data payloads.
9+
10+
The **IOT PROTOCOL** (*iot://*) is base on HTTP and MQTT protocols. Is a request-response model adapted for IoT context designed for low-bandwidth, low-power devices. Its minimum request size is 2 bytes without requiring the HOST param for all requests. Supports Full Duplex and can be used for real-time communication up to 255 bytes, middleweight request up to (2^16 -1) bytes (~65Kb) and streaming up to (2^32 -1) bytes (~4.29Gb). Can use TLS/SSL encryption to secure their communications.
11+
12+
13+
IOT PROTOCOL uses middlewares and router's filtering features based on [express nodejs module](https://expressjs.com/) at its Layer Application. Yes, you can use `.use(middleware)`, `.use('/path/to/your/resource', router)`, `response.send(data)` methods to handle the requests.
14+
15+
16+
## Features
17+
18+
- Lightweight protocol that minimizes network overhead
19+
- Minimum request size is 2 bytes
20+
- Request-response model like HTTP protocol
21+
- Adaptive requests methods for optimizing data length
22+
23+
---
824

925
## Preamble Version 1
1026

11-
```js
12-
VERSION \n
13-
METHOD + ID \n
14-
PATH \n
15-
[HEADERS \n]
16-
[BODY_CHAR + BODY_LENGTH \n BODY]
27+
```
28+
<MCB + LCB>
29+
[ID]
30+
[PATH + ETX]
31+
[HEADER + ETX]
32+
[BODY_LENGTH + BODY]
1733
```
1834

19-
### SEPARATOR char
35+
> `<...>` REQUIRED
2036
21-
SEPARATOR char serves to divide pieces of information
37+
> `[...]` OPTIONAL
2238
23-
* Type: `char` | `byte` | `uint8_t`
24-
* Size: 1 byte
25-
* Constant:
26-
* char: `\n`
27-
* hex: `0xA`
28-
* decimal: `10`
29-
* binary: `0b1010`
39+
---
40+
### [0] **MCB**: MSB_CONTROL_BYTE
3041

31-
### [0] VERSION
42+
The Most Significant Control Byte. **REQUIRED**
3243

33-
Version is the version of iot protocol. Used for compatibility.
44+
* Size: `1 byte`
45+
* Default: `0b00000100` = `4` = `0x4`
3446

35-
Format: `VERSION + SEPARATOR`. **REQUIRED** | **SINGLE**
47+
| Name | Description | Bit 7 | Bit 6 | Bit 5 | Bit 4| Bit 3 | Bit 2 | Bit 1 | Bit 0 | Default |
48+
| :--- | :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
49+
| VERSION | Version of iot protocol | X | X | X | X | X | X | | | *0b*000001 |
50+
| ID | Enable = 1 / Disable = 0 **ID**entification | | | | | | | X | | *0b*0 |
51+
| PATH | Enable = 1 / Disable = 0 **PATH** | | | | | | | | X | *0b*0 |
3652

37-
* Type: `byte` | `uint8_t`
38-
* Size: 1 byte
39-
* Example:
40-
* decimal: `1`
41-
* hex: `0x1`
42-
* binary: `0b00000001`
53+
#### Version:
54+
- Range: `from 1 up to 63`. Zero is reserved.
55+
56+
---
57+
### [1] **LCB**: LSB_CONTROL_BYTE
4358

44-
### [1] METHOD+ID
59+
The Least Significant Control Byte. **REQUIRED**
60+
* Size: `1 byte`
61+
* Default: `0b00000100` = `4` = `0x4`
4562

46-
Method ID identifies the method of request and its id.
63+
| Name | Description | Bit 7 | Bit 6 | Bit 5 | Bit 4| Bit 3 | Bit 2 | Bit 1 | Bit 0 | Default |
64+
| :--- | :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
65+
| METHOD | Type of request | X | X | X | X | X | X | | | *0b*000001 |
66+
| HEADER | Enable = 1 / Disable = 0 **HEADER** | | | | | | | X | | *0b*0 |
67+
| BODY | Enable = 1 / Disable = 0 **BODY** | | | | | | | | x | *0b*0 |
4768

48-
Format: `METHOD + ID + SEPARATOR`. **REQUIRED** | **SINGLE**
4969

50-
**METHOD**:
70+
#### METHOD:
5171

52-
Method is the reason why the request is made. **REQUIRED**
72+
- Range: `from 1 up to 63`. Zero is reserved.
5373

54-
* Type: `char`.
55-
* Size: 1 byte
56-
* Example: `R`
74+
Methods Types
5775

58-
* Methods types:
59-
- *Signal*: method used to send signals like events
60-
* char: `S`
61-
* decimal: `131`
62-
* hex: `0x83`
63-
* binary: `0b10000011`
76+
|Name | Description | MCB::ID | MCB::PATH | LCB::METHOD | LCB::HEADER | LCB::BODY | BODY::LENGTH | Minimum Total Length |
77+
|:-- | :-- | :--: | :--: | :--: | :--: | :--: | :-- | :--: |
78+
| *Signal* | Ligthweight signals like events | 0 | 0/1 | `0b000001` | 0/1 | 0/1 | *up to 255 bytes* | 2 bytes |
79+
| *Request* | Request that needs response | 1 | 0/1 | `0b000010` | 0/1 | 0/1 | *up to 65535 bytes* | 4 bytes |
80+
| *Response* | Request's response | 1 | 0 | `0b000011` | 0/1 | 0/1 | *up to 65535 bytes* | 4 bytes |
81+
| *Streaming* | Streaming data | 1 | 0/1 | `0b000100` | 0/1 | 0/1 | *up to (2^32 -1) bytes* | 6 bytes |
6482

65-
- *Request*: method used to do calls that needs a response
66-
* char: `R`
67-
* decimal: `130`
68-
* hex: `0x82`
69-
* binary: `0b10000010`
7083

71-
- *Response*: method used to responds a request
72-
* char: `r`
73-
* decimal: `114`
74-
* hex: `0x72`
75-
* binary: `0b1110010`
84+
---
7685

77-
**ID**:
86+
### ETX
7887

79-
Unsigned random number with up to 2^16 that identifies the request. **REQUIRED**
88+
**ETX** byte serves to determine end of text
89+
90+
* Type: `char` | `byte` | `uint8_t`
91+
* Size: `1 byte`
92+
* Constant:
93+
* char: `ETX` [Unicode - *End Of Text*](https://www.compart.com/en/unicode/U+0003)
94+
* hex: `0x3`
95+
* decimal: `3`
96+
* binary: `0b11`
8097

81-
* Type: `uint16_t` as Big Endian format.
82-
* Size: 2 bytes
98+
---
99+
100+
### [2] **ID**:
101+
102+
Unsigned random number with up to 2^16 that identifies the request. **SINGLE**
103+
104+
* Type: `uint16_t` as Big Endian format
105+
* Size: `2 bytes`
83106
* Example:
84107
* decimal: `276`
85108
* uint_8[2]: `[ 1 , 20 ]`
86109
* binary: `0b00000001 00010100`
87110

88-
### [2] PATH
111+
---
112+
### [3] **PATH**:
89113

90114
The path component contains data, usually organized in hierarchical
91115
form, that, serves to identify a resource [URI > 3.3 Path](https://www.rfc-editor.org/info/rfc3986).
92116

93-
Format: `PATH + SEPARATOR`. **REQUIRED** | **SINGLE**
117+
Format: `PATH + ETX`. **SINGLE**
118+
119+
#### **PATH**
94120

95121
* Type: `string`
96122
* Example: `/foo/bar`
97-
* Default: `/`
123+
124+
---
98125

99-
### [3] HEADERS
126+
### [4] **HEADERS**:
100127

101128
Headers are be Key Value Pair that serves to set an attribute value for the request. Case sensitive.
102129

103-
Format: `HEADER + SEPARATOR`. **OPTIONAL** | **MULTIPLE**
130+
Format: `HEADER + EXT`. **MULTIPLE**
104131

105-
**HEADER**
132+
#### **HEADER**
106133

107134
* Type: `string`
108135
* Format: `KEY + KEY_VALUE_SEPARATOR + VALUE`
@@ -111,44 +138,49 @@ Format: `HEADER + SEPARATOR`. **OPTIONAL** | **MULTIPLE**
111138
* *VALUE*:
112139
* Type: `string`
113140
* *KEY_VALUE_SEPARATOR*:
114-
* Constant:
115-
* char: `:`
116-
* decimal: `58`
117-
* hex: `0x3a`
118-
* binary: `0b00111010`
141+
* Type: `char` | `byte` | `uint8_t`
142+
* Size: `1 byte`
143+
* Constant:
144+
* char: `RS` [Unicode - *Information Separator Two - RecordSeparator RS*](https://www.compart.com/en/unicode/U+001E)
145+
* hex: `0x1E`
146+
* decimal: `30`
147+
* binary: `0b011110`
119148
* Example:
120-
* Single header: `foo:bar\n`
121-
* Multiple headers: `foo:bar\nlorem:ipsum\n`
122-
123-
### [4] BODY
149+
* Single header: `["foo", 0x1E, "bar", 0x3]`
150+
* Multiple headers: `["foo", 0x1E, "bar", 0x3, "lorem", 0x1E, "ipsum", 0x3]`
124151

125-
The final data to be sent for request receiver.
126152

127-
Format: `BODY_CHAR + BODY_LENGTH+SEPARATOR + BODY`. **OPTIONAL** | **SINGLE**
153+
------------------
128154

129-
**BODY_CHAR**:
155+
### [5] BODY
130156

131-
Identifies the body part. **REQUIRED**
157+
The final data to be sent for request receiver.
132158

133-
* Type: `char`
134-
* Size: 1 byte
135-
* Constant:
136-
* char: `B`
137-
* hex: `0x42`
138-
* decimal: `66`
159+
Format: `BODY_LENGTH + BODY`. **OPTIONAL** | **SINGLE**
139160

140-
**BODY_LENGTH**:
161+
#### **BODY_LENGTH**:
141162

142163
The body's length. **REQUIRED**
143164

144-
* Type: `uint16_t` as Big Endian format
145-
* Size: 2 bytes
146-
* Example:
147-
* decimal: `2321`
148-
* uint_8[2]: `[ 9 , 17 ]`
149-
* binary: `0b00001001 00010001`
165+
* Type: `uint8_t` | `uint16_t` | `uint32_t` as Big Endian format
166+
* Size: `1 / 2 / 4 bytes.` *Depends on the applied method*
167+
* Example:
168+
* `uint8_t`
169+
* decimal: `17`
170+
* uint_8[1]: `[ 17 ]`
171+
* binary: `0b00010001`
172+
173+
* `uint16_t`
174+
* decimal: `2321`
175+
* uint_8[2]: `[ 9 , 17 ]`
176+
* binary: `0b00001001 00010001`
150177

151-
**BODY**:
178+
* `uint32_t`
179+
* decimal: `67857`
180+
* uint_8[4]: `[ 0, 1, 9 , 17 ]`
181+
* binary: `0b00000000 00000001 00001001 00010001`
182+
183+
#### **BODY**:
152184

153185
The body / contents of request. **REQUIRED**
154186

@@ -157,6 +189,8 @@ The body / contents of request. **REQUIRED**
157189
* String: `the message`
158190
* Buffer: `[ 116, 104, 101, 32, 109, 101, 115, 115, 97, 103, 101 ]`
159191

192+
---
193+
160194
## Middlewares
161195

162196
@TODO Explains what is a middleware and how its works
@@ -175,3 +209,6 @@ The body / contents of request. **REQUIRED**
175209

176210
- `URI` Berners-Lee, T. Fielding, R. L. Masinter "Uniform Resource Identifier (URI): Generic Syntax" STD 66 RFC 3986 DOI 10.17487/RFC3986 <https://www.rfc-editor.org/info/rfc3986>.
177211

212+
- `UNICODE` Compart. Unicode Character <https://www.compart.com/en/unicode>
213+
214+
- `MQTT` MQTT. MQTT 5 Specification <https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html>

0 commit comments

Comments
 (0)