Robot Raconteur Client🔗ℹ

1 Installation🔗ℹ

  raco pkg install "git+https://github.com/johnwason/robotraconteur_racket?path=robotraconteur"

From a checkout of the repository, raco pkg install --link robotraconteur/ links the package to the working tree.

TLS uses the OpenSSL libraries that Racket’s openssl library loads. Discovery, and connecting to link-local IPv6 addresses without a zone, need Linux.

2 Quick start🔗ℹ

(require robotraconteur)

(define obj (rr-connect "rr+tcp://localhost:29200?service=reynard"))

(rr-object-type obj)              ; "experimental.reynard_the_robot.Reynard"

(rr-call obj "say" "Hello from Racket!")

(rr-set! obj "color" (vector 0.8 0.2 0.2))

(rr-get obj "robot_position")

(rr-call obj "teleport" 0.1 -0.2)

(rr-close obj)

Finding a service on the local network instead of naming its address:

(define found (rr-find-service-by-type "experimental.reynard_the_robot.Reynard"))

(define obj (rr-connect (car (rr-service-info-urls (car found)))))

3 Connecting🔗ℹ

URLs take these forms; nodename= and nodeid= may be added to the query to require a particular node:

• rr+tcp://host:port/?service=name: plain TCP.

• rrs+tcp://host:port/?service=name: Robot Raconteur TLS (see TLS).

• rr+ws://host:port/path?service=name: WebSocket, normally on the same port as rr+tcp.

• rr+wss://host[:port]/path?service=name: WebSocket over standard TLS, for example behind an HTTPS reverse proxy. The default port is 443.

IPv6 hosts go in brackets. A link-local address may carry its zone, [fe80::1%25eth0]; without one, the address is tried on every local interface with a link-local address at the same time and the first connection is kept, as the C++ core does.

username and credentials are sent for services that require authentication, for example (rr-connect url #:username "user" #:credentials (hash "password" "pass")).

The TCP connect gives up after 5 seconds, and the whole connect (TCP, TLS, the WebSocket upgrade and the Robot Raconteur handshake) after timeout seconds. On timeout everything opened for the attempt is closed and an exn:fail:robotraconteur with name "RobotRaconteur.ConnectionError" is raised. Requests on an open connection time out after 30 seconds.

ssl-context is used for rr+wss; see rr-make-ssl-context. tls-context is used for rrs+tcp; see rr-make-node-tls-context.

4 Values🔗ℹ

Values are converted to and from Robot Raconteur types using the service definitions:

Numbers inside a received varvalue are always vectors, because the wire does not distinguish a scalar from a one-element array.

5 Members🔗ℹ

6 Locks🔗ℹ

7 Errors🔗ℹ

8 TLS🔗ℹ

• the chain leads to a trusted root: by default the two Robot Raconteur node root certificates (2015 and 2020), which are built in;

• each certificate carries the critical Robot Raconteur extension for its place in the chain, and no other unknown critical extension;

• the node certificate is for CN=Robot Raconteur Node {nodeid} of the node that answered.

extra-roots are PEM files of further roots to trust; default-roots? #f leaves out the built-in ones. Client certificates are not supported.

9 Discovery🔗ℹ

Robot Raconteur nodes announce themselves with IPv6 link-local multicast (group FF02::BA86, UDP port 48653). These procedures send discovery requests on every interface with a link-local address, listen for timeout seconds, and return what answered. Discovery needs Linux.

10 Threads🔗ℹ

Each connection runs a few Racket threads: one reads and dispatches incoming messages, one sends keep-alive messages, and one runs listeners. Any number of threads may use a connection at the same time; requests are matched to their replies.

Event, wire and pipe listeners run one at a time, in arrival order, on the connection’s listener thread. A listener must not block. In particular it must not wait on a plain channel that another listener feeds. Hand slow work to another thread or use an async channel (racket/async-channel). A listener may call the service. Callbacks run in their own threads, so they may block.

All of these are Racket threads, so they share one operating system thread.