2013-11-21 02:41:10 +08:00
# Cylon.js
2013-10-18 14:55:48 +08:00
2013-11-25 05:20:28 +08:00
Cylon.js (http://cylonjs.com) is a JavaScript framework for robotics and physical computing using Node.js.
2013-10-18 14:55:48 +08:00
2013-11-25 05:20:28 +08:00
It provides a simple, yet powerful way to create solutions that incorporate multiple, different hardware devices at the same time.
2013-10-26 00:11:58 +08:00
2013-11-25 05:20:28 +08:00
Want to use Ruby on robots? Check out our sister project Artoo (http://artoo.io).
2013-11-21 02:41:10 +08:00
2013-11-25 05:20:28 +08:00
Want to use the Go programming language to power your robots? Check out our sister project Gobot (http://gobot.io).
2013-10-26 00:19:08 +08:00
2013-11-25 05:12:08 +08:00
[](http://travis-ci.org/hybridgroup/cylon)
2013-11-24 15:08:50 +08:00
2013-10-18 14:55:48 +08:00
## Getting Started
2013-10-23 05:18:31 +08:00
2013-11-21 02:41:10 +08:00
All you need to get started is the `cylon` module:
2013-10-18 14:55:48 +08:00
2013-11-21 02:41:10 +08:00
npm install cylon
2013-11-25 06:19:49 +08:00
Then install modules for whatever hardware support you want to use from your robot. For the example below, an Arduino using the Firmata protocol:
2013-11-21 02:41:10 +08:00
npm install cylon-firmata
2013-10-29 10:28:19 +08:00
2013-10-20 08:56:00 +08:00
## Examples
2013-10-23 05:18:31 +08:00
2013-11-25 06:19:49 +08:00
The example below connects to an Arduino, and every second turns the LED either on, or off.
The example requires that the Arduino has the Firmata sketch installed, and that it is connected on the port `/dev/ttyACM0` . You need to install Firmata on your Arduino, and to change the `port` parameter to match the port that your system is actually using.
Make sure to upload the "Standard Firmata" sketch or an equivalent Firmata sketch to your Arduino first. Without that code running on the Arduino, Firmata can't communicate with Cylon. You can find the example sketch in your Arduino software under "Examples > Firmata > StandardFirmata".
2013-10-23 05:18:31 +08:00
2013-11-25 05:20:28 +08:00
### JavaScript:
2013-11-21 02:41:10 +08:00
2013-10-18 14:55:48 +08:00
```javascript
2013-10-24 11:07:35 +08:00
var Cylon = require("cylon");
2013-10-23 05:18:31 +08:00
2013-10-20 08:53:53 +08:00
// Initialize the robot
2013-10-24 11:07:35 +08:00
var robot = Cylon.robot({
2013-11-09 03:04:22 +08:00
// Change the port to the correct port 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) {
2013-10-20 08:53:53 +08:00
// we do our thing here
2013-10-26 00:11:58 +08:00
every((1).second(), function() { my.led.toggle(); });
2013-10-20 08:53:53 +08:00
}
});
// start working
2013-10-20 11:31:29 +08:00
robot.start();
2013-10-18 14:55:48 +08:00
```
2013-10-23 09:33:54 +08:00
### CoffeeScript:
2013-11-21 02:41:10 +08:00
2013-11-25 01:44:57 +08:00
```
2013-10-24 11:07:35 +08:00
Cylon = require "cylon"
2013-10-23 05:18:31 +08:00
2013-10-20 08:53:53 +08:00
# Initialize the robot
2013-10-24 11:07:35 +08:00
robot = Cylon.robot
2013-10-20 08:53:53 +08:00
connection:
2013-10-26 15:26:02 +08:00
name: 'arduino', adaptor: 'firmata', port: '/dev/ttyACM0'
2013-10-23 05:18:31 +08:00
device:
2013-10-26 15:26:02 +08:00
name: 'led', driver: 'led', pin: 13
2013-10-23 05:18:31 +08:00
2013-10-26 00:11:58 +08:00
work: (my) ->
2013-10-20 08:53:53 +08:00
# we do our thing here
2013-10-26 15:26:02 +08:00
every 1.second(), -> my.led.toggle()
2013-10-20 08:53:53 +08:00
2013-10-26 15:26:02 +08:00
robot.start()
2013-10-18 14:55:48 +08:00
```
2013-11-25 05:20:28 +08:00
**Note:** before running any examples in the `examples/` dir from source, make sure to compile using `grunt coffee` first.
2013-10-26 04:50:53 +08:00
## Hardware Support
2013-10-26 15:09:47 +08:00
2013-11-25 05:20:28 +08:00
Cylon.js has a extensible system for connecting to hardware devices. The following robotics, physical computing, or software 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 )
2013-11-21 02:41:10 +08:00
- [Leap Motion ](https://www.leapmotion.com/ ) < ==> [Adaptor/Driver ](https://github.com/hybridgroup/cylon-leapmotion )
2013-11-27 10:09:58 +08:00
- [Pebble ](http://www.getpebble.com/ ) < ==> [Adaptor/Driver ](https://github.com/hybridgroup/cylon-pebble )
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 )
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 )
2013-10-26 15:09:47 +08:00
2013-11-21 02:41:10 +08:00
Support for many devices that use General Purpose Input/Output (GPIO) have
a shared set of drivers provded using the cylon-gpio module:
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
- LED
- Motor
- Maxbotix Ultrasonic Range Finder
- Servo
2013-10-29 10:28:19 +08:00
2013-11-21 02:41:10 +08:00
Support for devices that use Inter-Integrated Circuit (I2C) have a shared set of
drivers provded using the 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
- HMC6352 Digital Compass
2013-11-04 11:18:06 +08:00
2013-10-30 15:44:08 +08:00
More platforms and drivers are coming soon...
2013-10-26 04:50:53 +08:00
2013-12-04 05:53:11 +08:00
## CLI
Cylon has a Command Line Interface (CLI) so you can access important features
right from the command line.
2013-12-04 05:54:01 +08:00
Usage: cylon [command] [options]
2013-12-04 05:53:11 +08:00
2013-12-04 05:54:01 +08:00
Commands:
2013-12-04 05:53:11 +08:00
2013-12-04 05:54:01 +08:00
generate < name > Generates a new adaptor
2013-12-04 05:53:11 +08:00
2013-12-04 05:54:01 +08:00
Options:
2013-12-04 05:53:11 +08:00
2013-12-04 05:54:01 +08:00
-h, --help output usage information
-V, --version output the version number
2013-12-04 05:53:11 +08:00
### Generator
Want to integrate a hardware device we don't have Cylon support for yet? There's
a generator for that!
You can easily generate a new skeleton Cylon adaptor to
help you get started. Simply run the `cylon generate` command, and the
generator will create a new directory with all of the files in place for your
new adaptor module.
$ cylon generate awesome_device
Creating cylon-awesome_device adaptor.
Compiling templates.
$ ls ./cylon-awesome_device
Gruntfile.js
LICENSE
README.md
dist/
package.json
src/
test/
2013-10-21 05:11:58 +08:00
## Documentation
2013-11-21 02:41:10 +08:00
2013-11-25 05:20:28 +08:00
We're busy adding documentation to our web site at http://cylonjs.com/ please check there as we continue to work on Cylon.js
2013-10-30 15:44:08 +08:00
2013-12-03 03:59:55 +08:00
If you want to help us with some documentation on the site, you can go to [cylonjs.com branch ](https://github.com/hybridgroup/cylon/tree/cylonjs.com ) and then, follow the instructions.
2013-10-30 15:44:08 +08:00
Thank you!
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-11-25 05:20:28 +08:00
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using [Grunt ](http://gruntjs.com/ ).
2013-10-18 14:55:48 +08:00
## Release History
2013-11-21 02:41:10 +08:00
2013-11-25 05:12:08 +08:00
[](https://nodei.co/npm/cylon/)
2013-10-30 15:46:10 +08:00
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
2013-10-19 13:32:23 +08:00
Copyright (c) 2013 The Hybrid Group. Licensed under the Apache 2.0 license.
