2014-01-15 15:48:57 +08:00
[![Cylon.js ](https://raw.github.com/hybridgroup/cylon/gh-pages/images/elements/logo.png )](http://cylonjs.com)
2013-12-06 03:12:28 +08:00
2014-04-24 23:54:29 +08:00
Cylon.js is a JavaScript framework for robotics and physical computing built on
top of Node.js.
2013-10-18 14:55:48 +08:00
2014-04-24 23:54:29 +08:00
It provides a simple, but powerful way to create solutions that incorporate
multiple, different hardware devices concurrently.
2013-10-18 14:55:48 +08:00
2014-04-24 23:54:29 +08:00
Want to use Ruby on robots? Check out our sister project, [Artoo][].
2013-10-26 00:11:58 +08:00
2014-04-24 23:54:29 +08:00
Want to use Golang to power your robots? Check out our sister project,
[Gobot][].
2013-11-21 02:41:10 +08:00
2014-04-24 23:54:29 +08:00
[Artoo]: http://artoo.io
[Gobot]: http://gobot.io
2013-10-26 00:19:08 +08:00
2014-04-24 23:54:29 +08:00
## Build Status:
2013-11-21 02:41:10 +08:00
2014-05-22 10:46:10 +08:00
[![Build Status ](https://secure.travis-ci.org/hybridgroup/cylon.png?branch=master )](http://travis-ci.org/hybridgroup/cylon) [![Code Climate ](https://codeclimate.com/github/hybridgroup/cylon/coverage.png )](https://codeclimate.com/github/hybridgroup/cylon)
2013-10-23 05:18:31 +08:00
2014-04-24 23:54:29 +08:00
## Examples
2013-11-25 06:19:49 +08:00
2014-04-24 23:54:29 +08:00
### Arduino + LED
2013-11-25 06:19:49 +08:00
2014-04-24 23:54:29 +08:00
The below example connects to an Arduino over a serial connection, and blinks an
LED once per second.
2013-10-23 05:18:31 +08:00
2014-04-24 23:54:29 +08:00
The example requires that the Arduino have the Firmata sketch installed; which
can be obtained either through the Ardunio IDE or the `cylon arduino upload
firmata` command available in [cylon-cli][].
2013-11-21 02:41:10 +08:00
2013-10-18 14:55:48 +08:00
```javascript
2014-04-24 23:54:29 +08:00
var Cylon = require('cylon');
2013-10-23 05:18:31 +08:00
2014-04-24 23:54:29 +08:00
// define the robot
2013-10-24 11:07:35 +08:00
var robot = Cylon.robot({
2014-04-24 23:54:29 +08:00
// change the port to the correct one for your Arduino
2013-10-20 08:56:49 +08:00
connection: { name: 'arduino', adaptor: 'firmata', port: '/dev/ttyACM0' },
device: { name: 'led', driver: 'led', pin: 13 },
2013-10-23 05:18:31 +08:00
2013-10-26 00:11:58 +08:00
work: function(my) {
2014-04-24 23:54:29 +08:00
every((1).second(), my.led.toggle);
2013-10-20 08:53:53 +08:00
}
});
2014-04-24 23:54:29 +08:00
// connect to the Arduino and start working
2013-10-20 11:31:29 +08:00
robot.start();
2013-10-18 14:55:48 +08:00
```
2014-04-24 23:54:29 +08:00
### Parrot ARDrone 2.0
2013-12-06 03:12:28 +08:00
```javascript
2013-12-28 19:00:47 +08:00
var Cylon = require('cylon');
2013-12-06 03:12:28 +08:00
Cylon.robot({
connection: { name: 'ardrone', adaptor: 'ardrone', port: '192.168.1.1' },
device: { name: 'drone', driver: 'ardrone' },
work: function(my) {
my.drone.takeoff();
2014-04-24 23:54:29 +08:00
after((10).seconds(), my.drone.land);
after((15).seconds(), my.drone.stop);
}
}).start();
```
### Cat Toy (Leap Motion + Digispark + Servos)
```javascript
var Cylon = require('../..');
Cylon.robot({
connections: [
{ name: 'digispark', adaptor: 'digispark'},
{ name: 'leapmotion', adaptor: 'leapmotion', port: '127.0.0.1:6437' }
],
devices: [
{name: 'servo1', driver: 'servo', pin: 0, connection: 'digispark'},
{name: 'servo2', driver: 'servo', pin: 1, connection: 'digispark'},
{name: 'leapmotion', driver: 'leapmotion', connection: 'leapmotion'}
],
work: function(my) {
my['x'] = 90;
my['z'] = 90;
my.leapmotion.on('hand', function(hand) {
my['x'] = hand.palmX.fromScale(-300, 300).toScale(30, 150);
my['z'] = hand.palmZ.fromScale(-300, 300).toScale(30, 150);
});
every(100, function() {
my.servo1.angle(my['x']);
my.servo2.angle(my['z']);
console.log("Current Angle: " + my.servo1.currentAngle() + ", " + my.servo2.currentAngle());
});
2013-12-06 03:12:28 +08:00
}
}).start();
```
2014-04-24 23:54:29 +08:00
### Multiple Spheros + API Server
```javascript
var Cylon = require('cylon');
// tell the API server to listen for requests at
// https://localhost:4000
Cylon.api({ port: 4000 });
var bots = [
{ port: '/dev/rfcomm0', name: 'Thelma' },
{ port: '/dev/rfcomm1', name: 'Louise' }
];
var SpheroBot = function() {};
SpheroBot.prototype.connection = { name: "sphero", adaptor: "sphero" };
SpheroBot.prototype.device = { name: "sphero", driver: "sphero" };
SpheroBot.prototype.work = function(my) {
every((1).second(), function() {
console.log(my.name);
my.sphero.setRandomColor();
my.sphero.roll(60, Math.floor(Math.random() * 360));
});
};
for (var i = 0; i < bots.length ; i + + ) {
var bot = bots[i];
var robot = new SpheroBot();
robot.connection.port = bot.port;
robot.name = bot.name;
Cylon.robot(robot);
}
// start up all robots at once
Cylon.start();
```
[cylon-cli]: https://github.com/hybridgroup/cylon-cli
2013-10-18 14:55:48 +08:00
2013-10-26 04:50:53 +08:00
## Hardware Support
2013-10-26 15:09:47 +08:00
2014-04-24 23:54:29 +08:00
Cylon.js has an extensible syntax for connecting to multiple, different hardware
devices. The following platforms are currently supported:
2013-11-21 02:41:10 +08:00
- [Ardrone ](http://ardrone2.parrot.com/ ) < ==> [Adaptor/Drivers ](https://github.com/hybridgroup/cylon-ardrone )
- [Arduino ](http://www.arduino.cc/ ) < ==> [Adaptor ](https://github.com/hybridgroup/cylon-firmata )
2013-12-04 10:14:27 +08:00
- [Beaglebone Black ](http://beagleboard.org/Products/BeagleBone+Black/ ) < ==> [Adaptor ](https://github.com/hybridgroup/cylon-beaglebone )
2013-11-27 10:09:58 +08:00
- [Crazyflie ](http://www.bitcraze.se/ ) < ==> [Adaptor/Driver ](https://github.com/hybridgroup/cylon-crazyflie )
2014-01-26 14:25:11 +08:00
- [Digispark ](http://digistump.com/products/1 ) < ==> [Adaptor ](https://github.com/hybridgroup/cylon-digispark )
2014-01-15 15:56:41 +08:00
- [Joystick ](http://en.wikipedia.org/wiki/Joystick ) < ==> [Adaptor/Driver ](https://github.com/hybridgroup/cylon-joystick )
2014-01-14 03:04:13 +08:00
- [Keyboard ](http://en.wikipedia.org/wiki/Computer_keyboard ) < ==> [Adaptor/Driver ](https://github.com/hybridgroup/cylon-keyboard )
2013-11-21 02:41:10 +08:00
- [Leap Motion ](https://www.leapmotion.com/ ) < ==> [Adaptor/Driver ](https://github.com/hybridgroup/cylon-leapmotion )
2014-04-04 07:57:09 +08:00
- [Neurosky ](http://store.neurosky.com/products/mindwave-mobile ) < ==> [Adaptor/Driver ](https://github.com/hybridgroup/cylon-neurosky )
2014-01-15 15:56:41 +08:00
- [OpenCV ](http://opencv.org/ ) < ==> [Adaptor/Drivers ](https://github.com/hybridgroup/cylon-opencv )
2013-11-27 10:09:58 +08:00
- [Pebble ](http://www.getpebble.com/ ) < ==> [Adaptor/Driver ](https://github.com/hybridgroup/cylon-pebble )
2014-04-04 07:57:09 +08:00
- [Rapiro ](http://www.rapiro.com/ ) < ==> [Adaptor/Driver ](https://github.com/hybridgroup/cylon-rapiro )
2013-11-21 02:41:10 +08:00
- [Raspberry Pi ](http://www.raspberrypi.org/ ) < ==> [Adaptor ](https://github.com/hybridgroup/cylon-raspi )
- [Salesforce ](http://www.force.com/ ) < ==> [Adaptor/Driver ](https://github.com/hybridgroup/cylon-force )
2014-02-21 01:20:18 +08:00
- [Skynet ](http://skynet.im/ ) < ==> [Adaptor ](https://github.com/hybridgroup/cylon-skynet )
2013-12-04 10:14:27 +08:00
- [Spark ](http://www.spark.io/ ) < ==> [Adaptor ](https://github.com/hybridgroup/cylon-spark )
2013-11-21 02:41:10 +08:00
- [Sphero ](http://www.gosphero.com/ ) < ==> [Adaptor/Driver ](https://github.com/hybridgroup/cylon-sphero )
2014-04-04 07:57:09 +08:00
- [Tessel ](https://tessel.io/ ) < ==> [Adaptor/Driver ](https://github.com/hybridgroup/cylon-tessel )
2013-10-26 15:09:47 +08:00
2014-04-24 23:54:29 +08:00
Our implementation of GPIO (General Purpose Input/Output) allows for a shared
set of drivers supporting a number of devices:
2013-10-29 10:28:19 +08:00
2013-10-29 12:48:29 +08:00
- [GPIO ](https://en.wikipedia.org/wiki/General_Purpose_Input/Output ) < => [Drivers ](https://github.com/hybridgroup/cylon-gpio )
2013-11-27 10:09:58 +08:00
- Analog Sensor
- Button
2013-12-17 03:25:32 +08:00
- Continuous Servo
2014-04-04 07:57:09 +08:00
- IR Rangefinder
2013-11-27 10:09:58 +08:00
- LED
2014-02-07 09:50:21 +08:00
- MakeyButton
2013-11-27 10:09:58 +08:00
- Motor
- Maxbotix Ultrasonic Range Finder
- Servo
2013-10-29 10:28:19 +08:00
2014-04-24 23:54:29 +08:00
Additionally, we also support a number of I2C (Inter-Integrated Circuit) devices
through a shared `cylon-i2c` module:
2013-11-04 11:18:06 +08:00
- [I2C ](https://en.wikipedia.org/wiki/I%C2%B2C ) < => [Drivers ](https://github.com/hybridgroup/cylon-i2c )
2013-11-27 10:09:58 +08:00
- BlinkM
2014-04-04 07:57:09 +08:00
- BMP180
2013-11-27 10:09:58 +08:00
- HMC6352 Digital Compass
2014-02-07 09:50:21 +08:00
- LCD
- MPL115A2 Barometer/Thermometer
2014-04-04 07:57:09 +08:00
- MPU6050
2013-11-04 11:18:06 +08:00
2014-04-24 23:54:29 +08:00
We'll also have many more platforms and drivers coming soon, [follow us on
Twitter][Twitter] for updates.
[Twitter]: https://twitter.com/cylonjs
2013-10-26 04:50:53 +08:00
2013-12-06 03:12:28 +08:00
## Getting Started
### Installation
2014-04-24 23:54:29 +08:00
All you need to get started on a new robot is the `cylon` module:
2013-12-06 03:12:28 +08:00
npm install cylon
2014-04-24 23:54:29 +08:00
With the core module installed, now install the modules for whatever hardware
support you need. For the Arduino + LED blink example, we'll need the 'firmata',
'gpio', and 'i2c' modules:
2013-12-06 03:12:28 +08:00
2014-04-24 23:54:29 +08:00
npm install cylon-firmata cylon-gpio cylon-i2c
2013-12-06 03:12:28 +08:00
2013-12-04 05:53:11 +08:00
## CLI
2014-04-24 23:54:29 +08:00
Cylon has a Command-Line Interface counterpart in [cylon-cli][]. This tool lets
you access important features from the command line, and isn't dependent on
Cylon itself. Check it out at https://github.com/hybridgroup/cylon-cli.
2013-12-04 05:53:11 +08:00
2013-10-21 05:11:58 +08:00
## Documentation
2013-11-21 02:41:10 +08:00
2014-04-24 23:54:29 +08:00
We're busy adding documentation to our website, check it out at
[cylonjs.com/documentation][docs].
2013-10-30 15:44:08 +08:00
2014-04-24 23:54:29 +08:00
If you want to help with documentation, you can find some helpful instructions
on the [cylonjs.com branch][cylonjs-branch].
2013-12-03 03:59:55 +08:00
2014-04-24 23:54:29 +08:00
[docs]: http://cylonjs.com/documentation
[cylonjs-branch]: https://github.com/hybridgroup/cylon/tree/cylonjs.com
2013-10-21 05:11:58 +08:00
2013-10-18 14:55:48 +08:00
## Contributing
2013-11-21 02:41:10 +08:00
2013-12-28 10:32:42 +08:00
* All patches must be provided under the Apache 2.0 License
2013-12-28 18:58:52 +08:00
* Please use the -s option in git to "sign off" that the commit is your work and you are providing it under the Apache 2.0 License
* Submit a Github Pull Request to the appropriate branch and ideally discuss the changes with us in IRC.
2013-12-28 10:32:42 +08:00
* We will look at the patch, test it out, and give you feedback.
* Avoid doing minor whitespace changes, renamings, etc. along with merged content. These will be done by the maintainers from time to time but they can complicate merges and should be done seperately.
* Take care to maintain the existing coding style.
2014-04-24 23:54:29 +08:00
* Add unit tests for any new or changed functionality & lint and test your code using `make test` and `make lint` .
2013-12-28 18:58:52 +08:00
* All pull requests should be "fast forward"
2013-12-28 10:32:42 +08:00
* If there are commits after yours use “git rebase -i < new_head_branch > ”
* If you have local changes you may need to use “git stash”
2013-12-28 18:58:52 +08:00
* For git help see [progit ](http://git-scm.com/book ) which is an awesome (and free) book on git
2013-12-28 10:32:42 +08:00
2013-10-18 14:55:48 +08:00
## Release History
2013-11-21 02:41:10 +08:00
2014-04-22 07:15:30 +08:00
Version 0.13.3 - Fixes bug with disconnect functions not being called.
2014-04-18 02:13:28 +08:00
Version 0.13.2 - Use pure Express, adds server-sent-events, upd API.
2014-04-07 02:09:47 +08:00
Version 0.13.1 - Add API authentication and HTTPS support
2014-04-03 07:11:48 +08:00
Version 0.13.0 - Set minimum Node version to 0.10.20, add utils to global namespace and improve initialization routines
2014-03-29 04:51:51 +08:00
Version 0.12.0 - Extraction of CLI tooling
2014-03-13 04:18:34 +08:00
Version 0.11.2 - bugfixes
2014-03-05 00:57:30 +08:00
Version 0.11.0 - Refactor into pure JavaScript
2014-02-26 02:33:55 +08:00
Version 0.10.4 - Add JS helper functions
2014-02-21 03:22:04 +08:00
Version 0.10.3 - Fix dependency issue
2014-02-21 01:20:18 +08:00
Version 0.10.2 - Create connections convenience vars, refactor config loading
Version 0.10.1 - Updates required for test driven robotics, update Robeaux version, bugfixes
2014-02-07 09:50:21 +08:00
Version 0.10.0 - Use Robeaux UX, add CLI commands for helping connect to devices, bugfixes
2014-01-15 09:09:56 +08:00
Version 0.9.0 - Add AngularJS web interface to API, extensible commands for CLI
2013-12-17 03:25:32 +08:00
Version 0.8.0 - Refactored Adaptor and Driver into proper base classes for easier authoring of new modules
2013-12-04 10:27:32 +08:00
Version 0.7.0 - cylon command for generating new adaptors, support code for better GPIO support, literate examples
2013-11-26 07:47:57 +08:00
Version 0.6.0 - API exposes robot commands, fixes issues in driver/adaptor init
2013-11-25 05:12:08 +08:00
Version 0.5.0 - Improve API, add GPIO support for reuse in adaptors
Version 0.4.0 - Refactor proxy in Cylon.Basestar, improve API
2013-10-18 14:55:48 +08:00
2013-11-02 09:44:32 +08:00
Version 0.3.0 - Improved Cylon.Basestar, and added API
2013-11-25 05:12:08 +08:00
Version 0.2.0 - Cylon.Basestar to help develop external adaptors/drivers
Version 0.1.0 - Initial release for ongoing development
2013-11-07 22:23:59 +08:00
2013-10-18 14:55:48 +08:00
## License
2013-11-21 02:41:10 +08:00
2014-01-08 06:05:39 +08:00
Copyright (c) 2013-2014 The Hybrid Group. Licensed under the Apache 2.0 license.