Quick Start

Table of contents

The author’s native language is Chinese. This document is translated using AI.

Goals

With just a few lines of key code, the “device capabilities” can be mapped to the cloud or edge as a URI, allowing direct access and control of the device via HTTP.

Theory

                                                                 
   Device:PRINTER-001           Native │ Could or Edge                 
  ┌───────────────────────┐            │             ┌────────────┐ 
  │                       │            │             │            │ 
  │ /printer/action       │            │             │            │ 
  │ /printer/status       │  tcp/tls   │             │            │ 
  │                       │ ───────────┼───────────► │            │ 
  │                       │            │             │            │ 
  └───────────────────────┘            │             │            │ 
                                       │             │            │ 
   HTTPClient                          │             │            │ 
  ┌───────────────────────┐            │             │            │ 
  │ post $RTIO/PRINTER-001│            │             │            │ 
  │ req:                  │            │             │    rtio    │ 
  │ {                     │            │             │            │ 
  │   uri: /printer/action│            │             │            │ 
  │   data: cmd=start     │            │             │            │ 
  │ }                     │  http/https│             │            │ 
  │                       │ ───────────┼───────────► │            │ 
  │                       │ ◄─ ─ ─ ─ ─ ┼ ─ ─ ─ ─ ─ ─ │            │ 
  │ resp:                 │            │             │            │ 
  │ {                     │            │             │            │ 
  │   code: ok            │            │             │            │ 
  │   data: starting      │            │             │            │ 
  │ }                     │            │             │            │ 
  └───────────────────────┘            │             └────────────┘ 
   Phone/WEB/PC...

The above is a schematic diagram.

  • The device PRINTER-001 establishes a long connection with the RTIO server.
  • The HTTPClient sends a request to the device’s URI /printer/action.
  • The RTIO forwards the request to the device and returns the device processing result back to the HTTPClient via an HTTP response.

From the caller’s perspective, the “device capabilities” are mapped to the cloud through the RTIO service, without needing to worry about implementation or communication details. Build and Run

You need to have Golang (version 1.21 or above) and make tools installed.

git clone https://github.com/mkrainbow/rtio.git
cd rtio
make

After a successful build, executable files will be generated in the out directory, with the main files as follows.

$ tree out/
out/
├── examples
│   ├── certificates
│   ├── simple_device
│   └── simple_device_tls
├── rtio

Run the RTIO server, and you can view the help by using ./out/rtio -h.

$ ./out/rtio -disable.deviceverify -disable.hubconfiger -log.level=info
INF cmd/rtio/rtio.go:83 > rtio starting ...

In another terminal, simulate the device. The following log indicates a successful connection to the RTIO service.

$ ./out/examples/simple_device
INF internal/devicehub/client/devicesession/devicesession.go:660 > serving device_ip=127.0.0.1:47032 deviceid=cfa09baa-4913-4ad7-a936-3e26f9671b09
INF internal/devicehub/client/devicesession/devicesession.go:601 > verify pass

Open another terminal and use curl to request the device’s URI /rainbow through the RTIO service, sending the string “hello” to the device, which responds with “world”.

$ curl http://localhost:17917/cfa09baa-4913-4ad7-a936-3e26f9671b09 -d '{"method":"copost", "uri":"/rainbow","id":12667,"data":"aGVsbG8="}'
{"id":12667,"fid":0,"code":"OK","data":"d29ybGQ="}

Here, “aGVsbG8=” is the base64 encoding of “hello”, and “d29ybGQ=” is the base64 encoding of “world”. You can encode and decode in the terminal using the following commands.

$ echo -n "hello" | base64       # Encode
aGVsbG8=
$ echo -n "d29ybGQ=" | base64 -d # Decode
world

Device-Side Code

Below is the Golang implementation for the device side.

import (
    "github.com/mkrainbow/rtio-device-sdk-go/rtio"
)

func main() {

    // Connect to rtio service.
    session, err := rtio.Connect(context.Background(), *deviceID, *deviceSecret, *serverAddr)

    // ...
    
    // Register handler for URI.
    session.RegisterCoPostHandler("/rainbow", func(req []byte) ([]byte, error) {
        log.Printf("received [%s] and reply [world]", string(req))
        return []byte("world"), nil
    })

    // Session serve in the background.
    session.Serve(context.Background())

    // Do other things.
    time.Sleep(time.Hour * 8760)
}

Device SDK

Golang

RTIO device-side SDK, Golang version:

Typically suitable for devices running full Linux, such as ARM32-bit or higher single-board computers.

C

RTIO device-side SDK, C language version:

Suitable for resource-constrained devices, such as those running on real-time operating systems like FreeRTOS.