BB8-Commander

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #claude-code #codex #cli #developer-tools #react #windows

★ 72 Open GitHub ↗

A Node CLI Tool for the Sphero BB8 Robot every loves.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# BB8 Commander
A Node CLI Tool for Sphero BB8 Robot using the [Sphero Javascript SDK](http://sdk.sphero.com/community-apis/javascript-sdk/)

![BB8 Rolling like he's owning](http://i.imgur.com/00sZIf3.gif)

# Install
Not yet on npm so you'll have to do it the good'ol fasioned way with a cheeky git clone

* `npm install -g bb8-commander`
* `bb8 setup`
* Use commands below

If you are struggling to connect to BB8 it might be worth checking out the troubleshoot section of @saraford's [blog post](https://medium.com/@saraford/how-to-have-hubot-in-slack-send-commands-to-bb-8-700d2f3c953d#.4zjscutl83).

# Commands

### Utility Commands
* `bb8 setup` - Command to save your BB8 Unit UUID to config for future reference
* `bb8 disconnect` - Command to disconnect from your BB8 Unit

### Action Commands
* `bb8 disco` - Command to turn your BB8 Unit into a shining disco ball in the night
* `bb8 roll` - A simple command to make your BB8 Randomly roll in any direction.
* `bb8 desk-buddy` - A command to keep you company whilst working at your desk. Place in it's charging station to watch its head move round randomly.
* `bb8 weather --city="manchester" --country="uk" --api-key="ABCD"` - Command to turn your BB8 Unit into your very own weather reporter, uses OpenWeather so be sure to get your own API key
* `bb8 tweet --hash-tag="bb8" --delay=5000` - Command to search twitter and run the first hashtag it finds as a command. Eg a tweet "#disco #bb8" would run the `disco` command --consumer-key xxx --consumer-secret xxx --access-token-key xxx --access-token-secret xxx
* `bb8 power` - A command to get details of the battery state.
* `bb8 drive` - A command to enable you to take input from the keyboard and 'drive' your BB-8 with the arrow keys.
* `bb8 express --port=4000` - Command to run an express server which has a single POST endpoint which you can send a JSON object to. See below for more details.

### Express Server

Having the ability to run an Express server to issue commands to the BB8 unit opens up a bunch of possibilities. One of the main benefits of having an Express server is that you can integrate into [IFTTT](https://ifttt.com/) and at that point, you have entered the Internet of things.

To get started is really easy, all you need to do is run `bb8 express --port=4000` adn once your BB8 is connected, an Express server will be started.

You can then send commands directly to it via a POST request. It supports any SpheroSDK command as well as custom commands we have created. See below for some examples.

### Native Commands

With native commands, the response body will include information the BB8 exposes once that command has been executed. Read the Sphero documentation on what data it returns. http://sdk.sphero.com/community-apis/javascript-sdk/

#### Running the `color` command

Post Request - localhost:3000/

Request Body

```
{
  "mode":"sphero",
  "command":"color",
  "value": "yellow"
}
```

#### Running the `roll` command

Post Request - localhost:3000/

Request Body

```
{
  "mode":"sphero",
  "command":"roll",
  "value": [130, 50]
}
```

With this request, we are passing an array and that's because the roll command in Sphero SDK requires multiple parameters. This is just a simple way to pass those values to that command.

### Custom Commands

#### Running the `disco` command

Post Request - localhost:3000/

Request Body

```
{
  "mode":"custom",
  "command":"disco"
}
```

#### Running the `tweet` command

POST Request - localhost:3000/

Request Body

```
{
  "mode":"custom",
  "command":"tweet",
  "value": {
    "delay": 30,
    "consumerKey": "YOUR_CONSUMER_KEY",
    "consumerSecret": "YOUR_CONSUMER_SECRET",
    "accessTokenKey": "YOUR_ACCESS_TOKEN_KEY",
    "accessTokenSecret": "YOUR_ACCESS_TOKEN_SECRET"
  }
}
```

Obviously you wouldn’t pass your OAuth information like this (BB8 Commander supports environment variables for secure data) but the important thing to note here is, anything that can be passed to the CLI tool can also be passed into the express server endpoint.

A suite difference between native commands and custom commands is that native commands that require multiple parameters will be passed as an array whilst custom commands will be objects. The reason for this is custom commands are key value pairs due to them sharing the same code as the CLI tool.

### Stopping a custom command with the express server.
Some custom commands such as the desk-buddy command or the weather command loop forever until you tell BB8 to stop via the express server.

To stop a previous BB8 Command send the following POST Request. This will keep the express server running but will stop BB8 doing whatever he's doing.

Post Request - localhost:3000/

Request Body

```
{
  "mode":"custom",
  "command":"stop"
}
```

### Using BB8 Commander in your own projects.
It's cool being able to run a tool from your terminal but it's even cooler to be able to extend and build your own applications.

Run `npm install bb8-commander --save` within your projects root directory and here is some example code.

Some commands such as `disco` return a setInterval ID. This allows you to stop a command from continuously running by running `clearInterval(id)`

```
var bb8 = require('bb8-commander');
var appRootPath = require('app-root-path');

// Used to create a .bb8config file within your users home directory.
bb8.setup();

var name = 'express';
var options = {
  port: 4000
};

// Used to execute the command express 
bb8.executeCommand(name, options);

// Used to execute the command disco
var id = bb8.executeCommand('disco');

// Used to cancel the disco command.
clearInterval(id);

// Used to execute a custom command you have created.
var filePath = appRootPath + '/path/to/custom/command';
bb8.executeCustomCommand(filePath, options)

```

You can write custom command which can be executed via the executeCustomCommand function. A custom command accepts two parameters, the bb8 instance and any options you wish to pass in.

```
// example custom command
module.exports = function(bb8, options) {
  bb8.color(options.colour);
  bb8.roll(0, Math.floor(Math.random() * 180));
}
```

You can then execute this command like this

```
var bb8 = require('bb8-commander');
var appRootPath = require('app-root-path');

// Used to execute a custom command you have created.
var filePath = appRootPath + '/path/to/custom/command';
bb8.executeCustomCommand(filePath, {colour: '#000000'});
```

# Examples
* [How to have Hubot talk to BB-8 using Express Server](https://medium.com/@saraford/how-to-have-hubot-in-slack-send-commands-to-bb-8-700d2f3c953d) by [@saraford](https://github.com/saraford)

# Contributors
* [@mintuz](http://twitter.com/mintuz)
* [@shaunbent](http://twitter.com/shaunbent)
* [@citypaul](http://twitter.com/paulhammond)
* [@sud-puth](http://twitter.com/sud_)
* [@saraford](http://twitter.com/saraford)
* [@veaga](http://twitter.com/veaga)

# Want to contribute?

Go ahead, fork it, make a change, issue a PR. We welcome new actions and bug fixes.

BB8-Commander

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README