Software API 1.0 Provider
This page has been automatically translated and has not been reviewed in detail yet. Therefore, the translation might not be completely accurate.
With the "Software API", NeuroomNet has received a service (provider) for connecting generic components via general interfaces such as TCP. In the current version (1.0), the TCP interface is initially implemented, others may follow in the future.
General communication model
The software API is based on a well-defined communication model in which data packets are exchanged via an interface - for the exact processes see Communication Protocol. A distinction must be made between the physical data exchange (TCP/IP data stream, UDP/IP packets, web sockets, HTTP, ...) and the protocol scheme (JSON string, character string, binary data, ...).
Many of the interfaces listed already work with the exchange of packets and accommodate the communication model of the NeuroomNet Software API. The most important exception is TCP/IP, which is based on a data stream that does not inherently have any finer subdivisions. In the current version 1.0 of the software API, TCP is used for communication (originally for testing/evaluation purposes, among other things).
Packets and data streams
For the transmission of software API packets via a data stream, the packet is converted into a character string and, before transmission, the payload data is preceded by four bytes with the size of the packet in bytes. The transmission is Little Endian, i.e. the first byte is the lowest byte of the size (modulo 256) and so on. For now, the top (fourth and last byte) is reserved and must always be 0 - later extensions to the software API may use this to transmit special settings. The maximum size of a packet is 16,777,215 bytes, which should be more than enough.
Packets as strings
At the next level, a packet is ultimately always transmitted as a byte sequence. For many bindings this will simply be the original description of the package as a JavaScript object - JSON.stringify. However, for very simple components, evaluating JSON can be a certain challenge, which is why the service also offers an alternative encoding as a character string that is used for TCP/IP connections - switching per component is currently not possible, generally for later versions of the API but considered. In this encoding, a JSON of the type { "command": "DoAction", "id": "explode" } would be transmitted as a string "DoAction**<TAB>**explode". <TAB> is the "tab" - a single character with the code 0x09 (or '\t'). The exact coding is explained separately for the corresponding commands - see for example coding string in DoAction. In all cases, characters are transmitted in the UTF-8 notation without a special prefix (BOM Header).
Register components
The software API only supports so-called active components. An active component connects independently to the NeuroomNet Software API Server via the corresponding protocol. The following physical accesses are currently offered:
- TCP/IP (protocol name tcp) with encoding string: port 15400
The port used on the NeuroomNet side (default = 15400) can be changed to a different port number in the configuration.
The component establishes a corresponding connection and then waits for packets from the service, which then have to be answered appropriately. A globally unique name of the component should always be transmitted as id in the Description of the component. If this remains empty, it is fixed to the TCP/IP address of the computer that offers the component. This identifier is globally unique in NeuroomNet and can no longer be changed - from NeuroomNet's perspective, a different id is a different component. In particular, this also means that only one component can be executed per computer (address) without reporting a unique name - this is not a problem in many cases, for example with an RFID reader.
If an active component notices that the connection to the service has been interrupted (e.g. because it was restarted), it must of course be reestablished as soon as possible. However, measures to limit the network load must be taken into account - such as pauses between repeated login attempts. Of course, this also applies to the first registration: if the service is not available at this time, you must try to log in again until it is successful.
A practical example of using the software API can be found here: Link.