# Device Interface

SPAD.neXt can communicate with external devices like e.g. Arduino/Teensy via a very simple line based communication.

Request and reply on both sides will follow this format:

`<ChannelId>,<Param1>[,...,<ParamN>];`

{% hint style="success" %}
Thoughout the description of the device interface the following syntax will be used:

, is the seperator for parameters

; is the terminator of a command

/ is used as escape character

\[ ... ] defines optional parameter

\<Name> defines an actual value. This can be a number or a string (without quotes!)

Anything not enclosed in <> defines the exact string (without quotes!)
{% endhint %}

{% hint style="danger" %}
If `, / ;` are used within a parameter, they have to be escaped by a leading /.\
E.g.\
`15,Hello/, from Arduino;`
{% endhint %}

{% hint style="info" %}
For a SPAD.neXt compatible Arduino library import CmdMessenger (4.0) into the Arduino IDE (recommended) or clone the github repository at <https://github.com/thijse/Arduino-CmdMessenger>

There is also a customized version available at the SPAD.neXt GitHub (TODO LINK) which includes SPAD.neXt specific functions to make device programming more easy.
{% endhint %}

{% hint style="info" %}
The same protocol can be used to communicate with SPAD.neXt e.g. via a Websocket (TODO WEBSOCKET) and procide e.g. a custom webinterfaced device
{% endhint %}

## Channel-ID's

| ChannelID | Purpose                   | Direction        |
| --------- | ------------------------- | ---------------- |
| 0         | General Commands          | SPAD <--> Device |
| 1         | Data Commands             | Device -> SPAD   |
| 2         | SPAD.neXt Events          | SPAD -> Device   |
| 3         | Debug                     | Device -> SPAD   |
| 4         | Simulation Event          | Device -> SPAD   |
| 5         | Data Channel              | SPAD -> Device   |
| 6         | Device LED updates        | SPAD -> Device   |
| 7         | Device Display updates    | SPAD -> Device   |
| 8         | Device Input              | Device -> SPAD   |
| 9         | (reserved for future use) |                  |
| 10 .. 49  | Dedicated Data Channels   | SPAD <-> Device  |

{% hint style="info" %}
By default cmdMessenger is limited to a max of 50 channels to preserve device memory. You can change that by altering the line\
`#define MAXCALLBACKS 50`\
in cmdMessenger.h, however this is **not** recommended.
{% endhint %}

{% hint style="warning" %}
For the specs of the Serial V1 protocol (still supported but deprecated) please see [here](https://github.com/c0nnex/SPAD.neXt/wiki/Serial-Connection).
{% endhint %}

{% hint style="danger" %}
All \<tag> or \<targettag> are limited to the characters`A-Z,0-9,_`
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.spadnext.com/extending-and-apis/serial-connection.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.