JavaScript SDK

Documentation for QiMessaging JavaScript 1.0 is also available.

Introduction

The LibQi JavaScript SDK provides bindings to use LibQi services in JavaScript.

This library can be used to build HTML5 applications for your robot.

What is new

Here is a list of major changes since QiMessaging JavaScript 1.0:

• LibQi now uses Promise/A+;
• QiSession creation has been simplified;
• LibQi properties can now be used in JavaScript;
• QiSession.socket() has been removed so as to ease backward compatibility maintenance;
• Binary buffers are now serialized as Arrays of unsigned bytes instead of base 64 strings.

You may want to take a look at How to migrate from version 1.0 to 2.

Including the library

qi.js

The client page requires the inclusion of LibQi which is hosted on the robot.

<script src="/libs/qimessaging/2/qimessaging.js"></script>

Promise/A+

The library makes use of native ECMAScript 6 Promise/A+, which are now widely available.

If you are currently developing for an older browser, you can use a polyfill such as:

<script src="https://www.promisejs.org/polyfills/promise-6.0.0.min.js"></script>

Creating a QiSession

Initialization

The bindings provide only one class: QiSession. This object connects to the robot and gets proxies to services.

QiSession() can take three arguments:

• a callback which will be fired upon connection;
• a callback which will be fired upon disconnection;
• an optional host name or address which defaults to window.location.host.

QiSession(function (session) {
  console.log("connected!");
  // you can now use your QiSession
}, function () {
  console.log("disconnected");
});

Please note the QiSession object will actually be given to the first callback. You can then call service().

service()

You can call this function to get a JavaScript proxy to any service, also known as modules. Services are JavaScript bound objects providing corresponding NAOqi APIs through Calls, Signals and Properties.

QiService() takes a string corresponding to the service name, and returns a Promise which, upon fulfilled request, fires a callback with the proxy object.

QiSession.connect(function (session) {
  session.service("ALTextToSpeech").then(function (tts) {
    // tts is a proxy to the ALTextToSpeech service
  }, function (error) {
    console.log("An error occurred:", error);
  });
}, ...);

Using services

Calls

Service calls are only JavaScript function calls returning Promises. They are entirely asynchronous and take two callbacks, called respectively in case of success or failure.

tts.getLanguage().then(function (lang) {
  console.log("I speak " + lang);
}, function (error) {
  console.log("An error occurred: " + error);
});

Signals

Signals are JavaScript objects inside a service, that provide two methods, connect() and disconnect(), respectively to subscribe and unsubscribe. The first one will return an id that must be used by the second one for unregistration.

The example below connects to a signal, and once fired, disconnects.

var signalLink;
var serviceDirectory;

function onServiceAdded(serviceId, serviceName)
{
  console.log("New service", serviceId, serviceName);
  serviceDirectory.serviceAdded.disconnect(signalLink);
}

session.service("ServiceDirectory").then(function (sd) {
  serviceDirectory = sd;
  serviceDirectory.serviceAdded.connect(onServiceAdded).then(function (link) {
    signalLink = link;
  }, function (error) {
    console.log("An error occurred: " + error);
  });
);

Compatibility between Signals and ALMemory

ALMemory events cannot be directly used as LibQi signals. An extra step is needed, where ALMemory events are converted to signals using ALMemory::subscriber().

session.service("ALMemory").then(function (ALMemory) {
  ALMemory.subscriber("FrontTactilTouched").then(function (subscriber) {
    // subscriber.signal is a signal associated to "FrontTactilTouched"
    subscriber.signal.connect(function (state) {
      console.log(state == 1 ? "You just touched my head!" : "Bye bye!");
    });
  });
});

Properties

Qi properties behave like Signals, but provide two other methods: setValue() and value().

session.service("myservice").then(function (service) {
  service.prop.connect(function (value) {
    console.log("Value changed to", value);
    service.prop.value().then(function (v) {
      console.log("Current value is", v);
    });
  }).then(function (link) {
    service.prop.setValue(42); // will trigger callback
  });
});