qiloop

README

• About
• Frequently asked questions
• Status
• Usage
• Go API
• Tutorials
• Examples
• Command line interface
• Authentication
• Contributing

About

QiMessaging is a network protocol used to build rich distributed applications. It is created by SoftBank Robotics and is the foundation of the NAOqi SDK and the Pepper SDK.

libqi is the implementation of QiMessaging used in Pepper and NAO. It is open-source and developped here: https://github.com/aldebaran/libqi.

QiLoop is another implementation of QiMessaging. It has two main goals:

• being compatible with libqi
• being a platform for experimenting with the protocol

Disclaimer: QiLoop is not affiliated with SoftBank Robotics.

Frequently asked questions

Read the FAQ.

Status

Client and server sides are functional.

Service directory and log manager are implemented as part of the standalone server (launched with qiloop server).

Features:

• type supported: object, struct, values, map, list, tuple

• actions: method, signals and properties are fully supported

• cancel: client support only (see motion example)

• transport: TCP, TLS, UNIX socket and QUIC (experimental)

• authentication: read the credentials from $HOME/.qiloop-auth.conf

• service introspection: generate IDL from a running instance (use qiloop scan)

• IDL files: generate specialized proxy and service stub (use qiloop stub)

• stats and trace support

Usage

QiMessaging exposes a software bus to interract with services. Services have methods (to be called), signals (to be watched) and properties (signals with state). A naming service (the service directory) is used to discover and register services. For a detailed description of the protocol, please visit this analysis of QiMessaging.

To connect to a service, a Session object is required: it represents the connection to the service directory. Several transport protocols are supported (TCP, TLS and UNIX socket).

With a session, one can request a proxy object representing a remote service. The proxy object contains the helper methods needed to make the remote calls and to handle the incomming signal notifications.

Services have methods, signals and properties which are described in an IDL (Interface Description Language) format. This IDL file is process by the qiloop command to generate the Go code which allow remote access to the service (i.e. the proxy object).

Go API

Installation:

go get -u github.com/lugu/qiloop/...

Documentation: http://godoc.org/github.com/lugu/qiloop

Tutorials

• How to create a proxy to an existing service: follow the ALVideoDevice tutorial.

• How to create your own service: follow the clock tutorial.

Examples

Basic examples:

• hello world illustrates how to call a method of a service: this example calls the method 'say' of a text to speech service.

• signal registration illustrates how to subscribe to a signal: this example prints a log each time a service is added to the service directory.

Examples for NAO and Pepper:

• animated say uses ALAnimatedSpeech to animate the robot.

• posture puts the robot in a random position.

• motion move the robot forward and demonstrate how to cancel a call.

• memory uses ALMemory to react on a touch event.

Examples of service implementation:

• ping pong service illustrates how to implement a service.

• space service illustrates the client side objects creation.

• clock service completed version of the clock tutorial.

Command line interface

    $ qiloop -h                                                                                                                                                            /home/ludo/qiloop
    qiloop - an utility to explore QiMessaging

	 ___T_
	| 6=6 |
	|__`__|
     .-._/___\_.-.
     ;   \___/   ;
	 ]| |[
	[_| |_]

      Usage:
	qiloop [info|log|scan|proxy|stub|server|trace]

      Subcommands:
	info - Connect a server and display services info
	log - Connect a server and prints logs
	scan - Connect a server and introspect a service to generate an IDL file
	proxy - Parse an IDL file and generate the specialized proxy code
	stub - Parse an IDL file and generate the specialized server code
	server - Starts a service directory and a log manager
	trace - Connect a server and traces services

      Flags:
	   --version  Displays the program version string.
	-h --help  Displays help with available flag, subcommand, and positional value parameters.

Authentication

If you need to provide a login and a password to authenticate yourself to a server, create a file $HOME/.qiloop-auth.conf with you login on the first line and your password on the second.

Contributing

1. Fork me
2. Create your feature branch
3. Make changes (hopefully with tests and, why not, with documentation)
4. Create new pull request

Documentation

Overview

Package qiloop is an implementation of the protocol QiMessaging used to interract with the NAO and Pepper robots.

Introduction

QiMessaging is a software bus which exposes services. Services have methods (to be called), signals (to be watched) and properties (signals with state). A naming service (the service directory) is used to discover and register services. For a detailed description of the protocol, please visit https://github.com/lugu/qiloop/blob/master/doc/about-qimessaging.md

To connect to a service, a Session object is required: it represents the connection to the service directory. Several transport protocols are supported (currently TCP, TLS and UNIX socket).

With a session, one can request a proxy object representing a remote service. The proxy object contains the helper methods needed to make the remote calls and to handle the incomming signal notifications.

Services have methods, signals and properties which are described in an IDL (Interface Description Language) format. This IDL file is process by the `qiloop` command to generate the Go code which allow remote access to the service (i.e. the proxy object).

For example, here is an IDL file which describes a service which have two methods, one signal and one property:

package demo

interface RoboticService
	fn move(x: int, y: int)
	fn say(sentence: str)
	sig obstacle(x: int, y: int)
	prop battery(level: int)
end

Use 'qiloop proxy' commmand to generate the go code which gives access to the service:

$ go get github.com/lugu/qiloop/cmd/qiloop
$ qiloop proxy --idl robotic.idl.qi --output proxy_gen.go

The file proxy_gen.go contains a method called Services which gives access to the RoboticService service. The example bellow illustrate this.

In order to communicate with an existing service for which the IDL file is unknown, the `scan` command can be use to introspect a running instance of the service and generate its IDL description. The following produce the IDL file of LogManager service:

$ qiloop scan --qi-url "tcp://localhost:9559" --service LogManager --idl log_manager.idl.qi

In order to implement a new service, create an IDL file and run the `stub` command to generate the helper method to register the service:

$ qiloop stub --idl my_service.idl.qi --output stub_gen.go

The file stub_gen.go defines the interface to implement as well as the helper methods to register the service.

When offering a service, a Server is be used to handle incomming connection and to dispatch the requests.

The actual implementation of a service is provided by a object (Actor interface) which responds to call requests and emits the signals.

Example (Basic)

This example llustrates how to make a method call to a remote object. It uses the specialized proxy of the text to speech service.

package main

import (
	"github.com/lugu/qiloop"
	"github.com/lugu/qiloop/bus/services"
)

func main() {
	// imports the following packages:
	// 	"github.com/lugu/qiloop"
	// 	"github.com/lugu/qiloop/bus/services"

	// Create a new session.
	session, err := qiloop.NewSession(
		"tcp://localhost:9559", // Service directory URL
		"",                     // user
		"",                     // token
	)
	if err != nil {
		panic(err)
	}
	defer session.Terminate()

	// Obtain a proxy to the service
	textToSpeech, err := services.ALTextToSpeech(session)
	if err != nil {
		panic(err)
	}

	// Remote procedure call: call the method "say" of the service.
	err = textToSpeech.Say("Hi there !")
	if err != nil {
		panic(err)
	}
}

Index

• func NewSession(addr, user, token string) (bus.Session, error)
• type Authenticator
• type Server
  • func NewServiceDirectory(addr string, auth Authenticator) (Server, error)

Examples

• Package (Basic)

Functions

func NewSession

func NewSession(addr, user, token string) (bus.Session, error)

NewSession creates a new connection to the service directory located at address addr. Use non empty string if credentials are required, else provide empty strings. Example of address: "tcp://localhost:9559", "tcps://localhost:9443".

Types

type Authenticator

type Authenticator interface {
	Authenticate(user, token string) bool
}

Authenticator decides if a user/token tuple is valid. It is used to decide if an incomming connections is authorized to join the services.

type Server

type Server interface {
	// NewService register a new service to the service directory.
	NewService(name string, object bus.Actor) (bus.Service, error)
	// Session returns a local session object which can be used to
	// access the server without authentication.
	Session() bus.Session
	// Terminate stops the server.
	Terminate() error
	// Returns a channel to wait for the server terminaison.
	WaitTerminate() chan error
}

Server listens to an interface handles incomming connection. It dispatches the message to the services and objects.

func NewServiceDirectory

func NewServiceDirectory(addr string, auth Authenticator) (Server, error)

NewServiceDirectory starts a service directory listening at address addr. Possible addresses are "tcp://localhost:9559", "unix:///tmp/sock", "tcps://localhost:9443". Refer to qiloop/net for more details.