Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added new getting started guide for node js #357

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Added new getting started guide for node js #357

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
5011bb7
Added new getting started guide for node js
liam-b Mar 24, 2017
3036fbe
added 'getting started guides' for languages and tooling category
liam-b Mar 25, 2017
90e988b
Update getting-started-with-node-js.md
WasabiFan Mar 27, 2017
4f19dbb
added node and npm versions
liam-b Mar 30, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 42 additions & 50 deletions docs/tutorials/getting-started-with-node-js.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,74 +5,70 @@ author: "@liam-b"
---

{% include /style/icon.html type="warning" %}
Note that Node JS run really slowly on the EV3 brick and is limited to NPM version 0.10.29 which can be a problem when trying to install some libraries.
Note that Node.js runs frustratingly slowly on the EV3 brick and is limited to an old version of both Node.js and npm. You may want to consider using Python or another ev3dev-supported language instead.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It looks like non-EV3 stretch images are going to have node 4.7.2

{: .alert .alert-warning}

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It might make this page more approachable to have a one-sentence explanation of what Node.js is and what it's used for. You can format it as a "lead" paragraph if you'd like.

**Before you start, make sure that you have configured a network connection to
your ev3dev device and have opened an SSH connection to it.**
<p class="lead">
Node.js is a framework that allows you to run JavaScript as a local application. It is designed to make building servers and other asynchronous apps as easy as possible. In this tutorial, we'll show you how to get up-and-running with Node.js on ev3dev.
</p>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just do {: .lead} at the end here. Kramdown automatically creates the paragraph element.


## Installing ev3dev-lang
To install the library run:
**Before you start, make sure that you have [configured a network connection](/docs/networking/) on
your ev3dev device and have [opened an SSH connection](/docs/tutorials/connecting-to-ev3dev-with-ssh/) to it.**

## Installing ev3dev-lang (and quick-start)
To install the library which allows you to use ev3dev features, run the following command from your SSH connection:

```shell
npm install ev3dev-lang
```

Now whenever you want to use this in code, just write:

In all JavaScript files that you write from here forward, include the following line to import the module:
```javascript
var ev3dev = require('ev3dev-lang');
```

For a bit more info on this visit the ev3dev-lang [github page](https://github.com/wasabifan/ev3dev-lang-js).
For a bit more info on this visit the ev3dev-lang-js [GitHub page](https://github.com/wasabifan/ev3dev-lang-js).

## Nano
For this tutorial, we will be using nano. For more info on how to use nano check out the [nano cheat sheet](/docs/tutorials/nano-cheat-sheet).
## Exploring Node.js and ev3dev

## Hello world
Navigate to a project directory (e.g `~/src/js`) and make a new file with `touch test.js`
### Picking an editor: Nano

Open it with `nano test.js` and write:
```javascript
var test = 'hello world!';
console.log(test);
```
For this tutorial, we will be using a text editor called `nano`. For more info on how to use nano, check out the [nano cheat sheet](/docs/tutorials/nano-cheat-sheet). Feel free to use a different one if you know what you're doing.

Running `node test.js`should print `hello world!` to the console. If this worked you are ready to start coding with node!
### Hello world
To start, navigate to a project directory (e.g `~/src/js`) that we can store our files in:

## Motors
Plug a ev3 large motor into port A, then open `test.js` and write:
```shell
mkdir -p ~/src/js && cd ~/src/js
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This might be better as 2 separate lines instead of &&

```

{% include /style/icon.html type="warning" %}
This snippet of code will not work for any other motors!
{: .alert .alert-warning}
Create a JavaScript file and open it with `nano test.js`. In the opened editor, add the following code:

```javascript
var ev3dev = require('ev3dev-lang');

var motor = new ev3dev.LargeMotor('outA'); // create new motor plugged into port A called 'motor'

motor.runForever(200); // run motor at speed 200

setTimeout(function () {
motor.stop(); // stop the motor after a second
}, 1000)
console.log('hello world!');
```

If you get any errors when you try to run this, make sure your motor is plugged in correctly.
If you're using `nano`, refer to the [nano cheat sheet](/docs/tutorials/nano-cheat-sheet/) to learn how to save the file.

For other motors such as the `MeduimMotor`, check the [default supported motors](http://wasabifan.github.io/ev3dev-lang-js/modules/_motors_.html) list.
Running `node test.js`should print `hello world!` to the console. If this worked, you are ready to start coding with node!

And from reading the [documentation page](http://wasabifan.github.io/ev3dev-lang-js) you should be able to get a good idea of what methods you can use with the motor (things like `runForever()` and `runForTime()`). Then when you use it in code, it should look like:
### Motors
Let's try running a motor. Plug an EV3 motor into port A, then open `test.js` again and write:

```javascript
motor.doSomething(speed, otherArgument) // where doSomething can be replaced by any valid method.
var ev3dev = require('ev3dev-lang');

var motor = new ev3dev.Motor('outA'); // create new motor plugged into port A called 'motor'
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Might want a link to http://www.ev3dev.org/docs/platform-comparison/ here to get the port names for non-EV3 hardware.


motor.runForTime(3000, 500); // run the motor for 3 seconds at 500 degrees/second
```

You can also **reset** and **read** the position of a motor using `motor.reset()` and `motor.position`.
Save the file and run it. Again, you can run the file with `node test.js`. If you get any errors when you try to run this, make sure that your motor is plugged in correctly.

## Sensors
Plug a ev3 color sensor into port 1, then edit `test.js` again appending this to the bottom:
You can refer to the [motor documentation page](http://wasabifan.github.io/ev3dev-lang-js/classes/_motors_.motor.html) to learn about other things you can do with motors (such as using the `runForever()` and `runToRelativePosition()` methods).

### Sensors
Plug an EV3 color sensor into port 1, then edit `test.js` again appending this to the bottom:

```javascript
var sensor = new ev3dev.ColorSensor('in1'); // create new color sensor called 'sensor'. in1 refers to port 1
Expand All @@ -82,19 +78,15 @@ setInterval(function () {
}, 300)
```

For other sensors, check the [default supported sensors](http://wasabifan.github.io/ev3dev-lang-js/modules/_sensors_.html) list.

To change a sensors mode you'll need to check what modes it has by looking at the [ev3dev sensor list](http://docs.ev3dev.org/projects/lego-linux-drivers/en/ev3dev-jessie/sensor_data.html) and use:
If you run your file now, you should see it continuously log the brightness that the sensor is detecting to the console. To stop the code, press <kbd>Ctrl</kbd>+<kbd>C</kbd>.

```javascript
sensor.mode = 'NEW-MODE'; // where 'NEW-MODE' can be replaced by any valid mode
```
For other sensors, check out the [sensors documentation page](http://wasabifan.github.io/ev3dev-lang-js/modules/_sensors_.html). Every sensor has a set of "properties" that can be read; you should refer to the documentation site to see which properties can be used.

And then using `sensor.someValueAcessor` will return the sensor value, where `someValueAcessor` can be replaced by any valid accessor (also found on the [default supported sensors](http://wasabifan.github.io/ev3dev-lang-js/modules/_sensors_.html) list by clicking on the sensor you are using)
### Next steps
You've now learned the basics of using Node.js with ev3dev! For info on all supported sensors, motors and other documentation visit the [GitHub page](https://github.com/wasabifan/ev3dev-lang-js) and the [documentation page](http://wasabifan.github.io/ev3dev-lang-js).

## Next steps
So that's the basic overview of how to use node with ev3dev! For info on all supported sensors, motors and other documentation visit the [github page](https://github.com/wasabifan/ev3dev-lang-js) and the [documentation page](http://wasabifan.github.io/ev3dev-lang-js).
The documentation website has a list of "modules" along the side; click on each to visit the detail page for that module. When looking at the page for a specific class, pay attention to the **methods** and **accessors** (e.g., the large motor has **methods** such as `runForever()` and `runForTime()`, and the color sensor has **accessors** such as `reflectedLightIntensity`and `ambientLightIntensity`).

The documentation page looks a bit confusing, but what you really need to worry about are the names of the classes and the **methods** / **accessors**. (eg. the large motor has **methods** such as: `runForever()`, `runForTime()` etc and the color sensor has **accessors** such as: `reflectedLightIntensity`, `ambientLightIntensity` etc)
The [sensor list](http://docs.ev3dev.org/projects/lego-linux-drivers/en/ev3dev-jessie/sensor_data.html) and the [motor list](http://docs.ev3dev.org/projects/lego-linux-drivers/en/ev3dev-jessie/motor_data.html) are the best place to look to see what you can do with ev3dev.

The [sensor list](http://docs.ev3dev.org/projects/lego-linux-drivers/en/ev3dev-jessie/sensor_data.html) and the [motor list](http://docs.ev3dev.org/projects/lego-linux-drivers/en/ev3dev-jessie/motor_data.html) are both really useful pages aswell.
Happy coding!