Your Kitsunei Creator App comes with a set of APIs that help you communicate with your blocks using JavaScript.

To facilitate your development Kitsunei offers SDKs to help you access the Hub APIs. There are currently 2 SDK available for Javascript development:

Desktop SDK: Designed to produce self-contained Node.js applications.

Web SDK: Designed for web interfaces and virtual blocks.

In this article, we will focus on how to access the Hub APIs using the Script Virtual block since it is the easiest way to get started.

Note: This guide assumes you have a moderate understanding of Javascript programming.

For more information about the Script Block and the custom functions it offers, read our Communicating With Other Virtual Blocks guide.

The Kitsi Object

From within the Script block the WebSDK can be accessed through the global object ‘Kitsi’, which exposes the 'APICall()' function used call Hub API methods.

Keep in mind that ALL API calls are asynchronous, and it is recommended to use async await to call them. 

For a complete list of the available API calls visit the API reference site.

The BlockTypes Object

In addition to the ‘Kitsi’ object, you can access the list of block types from the BlockTypes object. Visit the SDK documentation page to see all the block types you can use.

Controlling The Motor Driver Using APIs

First, you need to get a reference of your MotorDriver block, for this we use the ‘waitForBlock’ function from the WebSDK, which is available via the global object ‘Kitsi’

var motor_driver = await Kitsi.waitForBlock(BlockTypes.MotorDriver);

If you have multiple Motor Driver blocks online and want to control one in particular, pass a second argument with the uid of the device you wish to use:

var uid = {uid:{"high":12,"med":23421,"low":6225953}}; // Unique identifier
var motor_driver = await Kitsi.waitForBlock(BlockTypes.MotorDriver, uid);

If you want to know which blocks are currently online and their properties (such as the unique identifier), use the getConnectedBlocks() method:

var blockList = await Kitsi.getConnectedBlocks();
console.log("Blocks: %j", blockList);

Now that you have a reference of your block, you can now invoke any of the available Hub APIs. Each hardware block has specific API methods you can invoke, to know more about the list of available methods for all the blocks, please visit the reference page. In our case, we will use the 'SetSpeed' method to make our brushed motors connected to outputs 0 and 3 rotate at 100% and 50% speed respectively.

try{
  await Kitsi.APICall('SetSpeed', [{0: 100, 3: 50}], block);
}catch(e){
  console.error("Error calling API: %s", JSON.stringify(e));
}

Keep in mind that for the above code to work the outputs 0 and 3 of your MotorDriver MUST be configured to ‘Brushed’. You can change the block’s settings directly from the interface or you can also use the SDK to do that:

try{
    const settings = await Kitsi.readSettings(block);
    // Change  outputs 0 and 3 to drive 'brushed' motors
    // Check the documentation to see all the available modes: http://reference.api.kitsunei.com/module-MotorDriver.html#.DeviceMode)

    settings.Custom.DeviceMode[0] = 2;
    settings.Custom.DeviceMode[3] = 2;

    // Store the new settings
    await Kitsi.saveSettings(block, settings);
    console.log("New Settings Stored!")
}catch(e){
    console.error("Error: %s", JSON.stringify(e));
}

You could also program the motors to stop rotating after 1 second by modifying the PowerTimeout section of the settings:

settings.Custom.PowerTimeout[0] = 1000;
settings.Custom.PowerTimeout[3] = 1000;

Putting it all together your code should look like this:

// Remember all asynchronous methods should be called from 
// an async function!
(async function(){

  // Wait for any MotorDriver block to be online
  var block = await Kitsi.waitForBlock(BlockTypes.MotorDriver);

  try{
    const settings = await Kitsi.readSettings(block);
    console.log("Settings: %j", settings);

    // Change outputs 0 and 3 to drive 'brushed' motors
    settings.Custom.DeviceMode[0] = 2;
    settings.Custom.DeviceMode[3] = 2;

    // Add timeouts to those output, so the motors stop rotating after 1 seconds
    settings.Custom.PowerTimeout[0] = 1000;
    settings.Custom.PowerTimeout[3] = 1000;

    // Store the new settings
    await Kitsi.saveSettings(block, settings);
    console.log("New Settings Stored!");


    await Kitsi.APICall('SetSpeed', [{0: 100, 3: 50}], block);
    console.info("The motors should be rotating now!");
  }catch(e){
    console.error("Error: %s", JSON.stringify(e));
  }
}());

We highly recommend reading the Hub APIs reference page and get familiar with the APIs of the block you want to control.