qiloop

package module
Version: v0.13.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 17, 2020 License: MIT Imports: 3 Imported by: 0

README

qiloop

Build Status CircleCI Go Report Card codecov Test Coverage Maintainability Documentation license stability-unstable Release

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

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:

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)
	}
}
Output:

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

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.

Source Files

Directories

Path Synopsis
bus
net
cmd
examples
animated-say
Package main illustrates how to make a method call to a remote object.
Package main illustrates how to make a method call to a remote object.
memory
Package main illustrates how to make a method call to a remote object.
Package main illustrates how to make a method call to a remote object.
motion
Package main demonstrates how to move the robot through ALMotion
Package main demonstrates how to move the robot through ALMotion
pong
Package pong contains the implementation of the PingPong service.
Package pong contains the implementation of the PingPong service.
pong/cmd/client
Package main illustrate how to interract with the PingPong service.
Package main illustrate how to interract with the PingPong service.
pong/cmd/service
Package main illustrate how to use the pong package to create a service "PingPong" registered to the service directory.
Package main illustrate how to use the pong package to create a service "PingPong" registered to the service directory.
posture
Package main demonstrates how to move the robot through ALMotion
Package main demonstrates how to move the robot through ALMotion
say
Package main illustrates how to make a method call to a remote object.
Package main illustrates how to make a method call to a remote object.
signal
Package main illustrates how to subsribe to a signal in order to receive events.
Package main illustrates how to subsribe to a signal in order to receive events.
space
Package space contains the implementation of the Spacecraft and Bomb objects.
Package space contains the implementation of the Spacecraft and Bomb objects.
video
Package main demonstrates show to connect ALVideoDevice to retreive an image.
Package main demonstrates show to connect ALVideoDevice to retreive an image.
meta
idl
type
object
file generated.
file generated.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL