JavaScript API

Plugins Functions

List of available functions to control plugins life cycle.

NodeJS	Description
SARAH.run()	Run script with given data
SARAH.call()	Like run without rule dispatch
SARAH.last()	Run latest script again (v2.8)
SARAH.exists()	Check if module/phantom exists (v2.8)
SARAH.remote()	Run client remote commande (play, pause, …)

To run a plugin like an HTTP request:

// Run eedomus plugin with some parameters
SARAH.run('eedomus', { 'periphId' : id , 'periphValue' : value });
   
// Call eedomus plugin without forwarding result to Rule Engine
SARAH.call('eedomus', { 'periphId' : LUMENS}, function(options){ /* do next stuff */  });

# HTTP Functions

List of available function sending an HTTP Request to Client. Request are sent using SARAH.remote()

See also: Client HTTP Server

NodeJS	Request	Description
SARAH.speak()	tts=...&sync=...	Trigger Text to Speech (can be sync or async)
SARAH.shutUp()	notts=...	Stop speaking
SARAH.play()	play=...	File.mp3 to play
SARAH.pause()	pause=...	File.mp3 to stop
SARAH.keyText()	keyText=...	Text to type
SARAH.runApp()	run=...&runp=...	Application path to run and parameters
SARAH.activate()	activate=...	Application to put foreground
SARAH.face()	face=...	start/stop face recognition
SARAH.gesture()	gesture=...	start/stop gesture recognition
below the requests only
	picture=...	Take a picture, store it and return in response (only main Sensor)
	height=...	Return user height based on it's forearm (value tts to speech)
	keyUp=...	Key to press
	keyDown=...	Key to press
	keyPress=...	Key to press
	keyMod=...	Key modifier
	status=...	returns "speaking" if SARAH is currently speaking
	recognize=...	Perform speech recognition on given audio path or upload
	listen=...	Start / Stop listening
	context=...	Activate context grammar

JSDocs

SARAH.exists(module)

Parameters

• {String} module : check if a module/phantom is available

Return

If the module is available the function will return true, or false if it's not available.

Comments

From SARAH v2.8.

Example: if you have the plugin "freebox" you can test SARAH.exists("freebox").

SARAH.speak(sentence, [callback])

Parameters

• {String} Sentence : this is the sentence that SARAH will say
• {Function} [callback] : (optional) this is a callback function that will be called when the sentence has been said

Comments

The call is synchronous if you don't use a second parameter. Examples:

SARAH.speak("Hello");
SARAH.speak("world");
SARAH.speak("I'm Sarah");

Then it will send 3 HTTP requests and only 1 will be said by SARAH. It's because the TTS requests are ignored when SARAH is currently speaking.

From SARAH V3.0 it's possible to change this behavior with cascading calls (=asynchronous):

SARAH.speak("Hello", function(){
  SARAH.speak("world", function(){
    SARAH.speak("I'm Sarah", function(){
      // ...
    })
  })
})

It's still possible to use SARAH.shutUp() at any time to stop SARAH for speaking.

Note - you can check the status of SARAH in sending the request http://127.0.0.1:8888/?status=true : if it returns speaking then it means SARAH is current speaking, otherwise it returns nothing.

SARAH.play(file)

Parameters

• {String} file : relative path to a MP3 or WAV file (e.g. media/song.mp3), or a web URL (e.g. http://www.site.com/file.mp3)

Comments

This function will play a sound file. The sounds can be parallelized. However there is a timeout after 2 minutes that will automatically stop the playing.

Regarding the WAV file, it must be a 88 kb/s encoded file (the 64 kb/s won't work).

SARAH.pause(file)

Parameters

• {String} file : relative path to a MP3 or WAV file (e.g. media/song.mp3), or a web URL (e.g. http://www.site.com/file.mp3)

Comments

This function will stop/pause a sound that is currently playing. The file parameter must be the same used for SARAH.play().

SARAH.runApp({run, [runp]})

Parameters

• {Object} the options
  • {String} run : the path to the program to execute
  • {String} [runp] : use this one to pass some parameters to the program

Comments

This function call the C# function Process.Start(processName, param). Windows' rule: never use space or custom chars in path.

If you want to launch/run an executable program on client side:

  // Lauching XBMC
  SARAH.runApp('E:\\XBMC12\\XBMC.exe');

  // Lauching Spotify with a song
  SARAH.runApp('C:\\Program Files (x86)\\Spotify\\spotify.exe', '"spotify:track:6ilfuI7O1vUfKf4TQ9fJRb"');

If you want to launch/run an executable program on server side:

exports.action = function(data, callback, config, SARAH) {
  // see http://nodejs.org/api/child_process.html#child_process_child_process_exec_command_options_callback
  var exec = require('child_process').exec;
  
  // note: below we use double quotes inside (") the simple quotes (')
  // because we have some blank spaces in the path
  // for a relative path to SARAH you can use %CD%
  // example: var process = '%CD%\\\\plugins\\\\myplugin\\\\bin\\\\xbmc.bat';
  var process = '"C:\\\\Program Files (x86)\\\\XBMC\\\\XBMC.exe"'; 
  var child = exec(process, function (error, stdout, stderr) {
    if (error !== null) console.log('exec error: ' + error);
  });

  callback({'tts': "Je lance XBMC."});
}