101 lines
2.7 KiB
Markdown
101 lines
2.7 KiB
Markdown
# Simple Serial Protocol (SSP)
|
|
|
|
SSP is a easy-to-use serial protocol system for arduino type devices.
|
|
|
|
## Installation
|
|
|
|
### Using Arduino IDE
|
|
|
|
Download repository as ZIP and import it using the IDE.
|
|
|
|
### Using PlatformIO (Recommended)
|
|
|
|
Add the following dependency to your ``platform.ini`` file under ``lib_deps``.
|
|
|
|
```ini
|
|
; SSP
|
|
https://git.aterve.com/Frozenverse/SimpleSerialProtocol.git
|
|
```
|
|
|
|
``platform.ini`` should look something like this:
|
|
|
|
```ini
|
|
[env:megaatmega2560]
|
|
platform = atmelavr
|
|
board = megaatmega2560
|
|
framework = arduino
|
|
|
|
lib_deps =
|
|
; SSP
|
|
https://git.aterve.com/Frozenverse/SimpleSerialProtocol.git
|
|
|
|
```
|
|
|
|
## Usage
|
|
|
|
SimpleSerialProtocol has a very simple API so it should be very easy to implement it. Look at ``ssp.ino`` in the examples folder for a complete example.
|
|
|
|
The protocol works as following, each packet has 3 seperate stages.
|
|
|
|
### ID
|
|
This could be the device or service you want to reach.
|
|
|
|
### Command
|
|
This is the command you want to send to the device or service.
|
|
|
|
### Data
|
|
This is the data you want to send to the device or service.
|
|
|
|
Of course you could change the use of any of these values to fit your needs.
|
|
A complete packet would look like this:
|
|
|
|
```
|
|
<ID_HERE:COMMAND_HERE:DATA_HERE>
|
|
```
|
|
|
|
As you can see the packet starts and ends with ``< - >`` characters and the stages are seperated with `` : `` characters.
|
|
|
|
`This means you can't use any of these characters as data in the packets!!`
|
|
|
|
Include SSP and define a new device.
|
|
```c++
|
|
#include <SimpleSerialProtocol.h>
|
|
|
|
// Define new device
|
|
SimpleSerialProtocol device;
|
|
```
|
|
|
|
Initialize the serial device and connection.
|
|
First parameter is a serial object. For example; the mega 2560 has 4 serial channels (RX0/TX0 through RX3/TX3) so Serial, Serial1, Serial2 ... etc.
|
|
Second parameter is the baud rate.
|
|
```c++
|
|
void setup() {
|
|
// Initialize serial device on index 0 with a baud rate of 115200
|
|
device.init(Serial, 115200);
|
|
}
|
|
```
|
|
|
|
Now create a method (with a packet parameter) which will be called when a packet is received. In the main loop call ``receivePackets`` with the callback function as parameter regularly. (more times the better)
|
|
```c++
|
|
void onPacket(Packet packet) {
|
|
Serial.println("Received Packet!");
|
|
Serial.println(packet.id);
|
|
Serial.println(packet.command);
|
|
Serial.println(packet.data);
|
|
Serial.println("----------------");
|
|
}
|
|
|
|
void loop() {
|
|
device.receivePackets(onPacket);
|
|
delay(1);
|
|
}
|
|
```
|
|
To send packets you can use the ``sendPacket`` method.
|
|
```c++
|
|
deviceOne.sendPacket("IDPacket", "Commandhere", "testtest");
|
|
```
|
|
## Contributing
|
|
Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.
|
|
|
|
## License
|
|
[MIT](https://www.gnu.org/licenses/gpl-3.0.en.html) |