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.

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
Changes from 1 commit
Commits
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
100 changes: 100 additions & 0 deletions docs/tutorials/getting-started-with-node-js.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
---
title: Getting Started with Node JS
group: software-languages
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.
Copy link
Member

Choose a reason for hiding this comment

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

run -> runs

Copy link
Member

Choose a reason for hiding this comment

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

"really" sounds mildly unprofessional in this context. Can we use another word there?

Copy link
Member

Choose a reason for hiding this comment

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

NPM is npm

Copy link
Member

Choose a reason for hiding this comment

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

It's also limited to an equivalently old Node.js version, which should also be mentioned.

{: .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
Copy link
Member

Choose a reason for hiding this comment

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

Can you link to the tutorials that we have for these tasks?

your ev3dev device and have opened an SSH connection to it.**

## Installing ev3dev-lang
To install the library run:
Copy link
Member

Choose a reason for hiding this comment

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

Without an explicit mention that this should be run via SSH, some people will try running this on their PC 😆


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

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

```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).
Copy link
Member

Choose a reason for hiding this comment

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

github -> GitHub


## 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).

## Hello world
Navigate to a project directory (e.g `~/src/js`) and make a new file with `touch test.js`
Copy link
Member

Choose a reason for hiding this comment

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

e.g -> e.g.

Copy link
Member

Choose a reason for hiding this comment

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

Period after sentence


Open it with `nano test.js` and write:
```javascript
var test = 'hello world!';
console.log(test);
```

Running `node test.js`should print `hello world!` to the console. If this worked you are ready to start coding with node!
Copy link
Member

Choose a reason for hiding this comment

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

Although I've often formatted the name as "node" or "Node," they officially use "Node.js"; I think we should align with that wherever possible.


## Motors
Plug a ev3 large motor into port A, then open `test.js` and write:
Copy link
Member

Choose a reason for hiding this comment

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

a ev3 -> an EV3

Copy link
Member

Choose a reason for hiding this comment

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

People might need to be reminded how to open files again. Maybe you can just link to the cheat sheet everywhere that you mention nano 😆 Your choice.


{% include /style/icon.html type="warning" %}
This snippet of code will not work for any other motors!
Copy link
Member

Choose a reason for hiding this comment

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

Mention what other motors the user might have (so they know how to tell them apart)

{: .alert .alert-warning}

```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
Copy link
Member

Choose a reason for hiding this comment

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

I'd prefer to not tell people that this is even an option for running for a length of time, given that there is a runForTime method. Do you have any other ideas for a good demo?


setTimeout(function () {
motor.stop(); // stop the motor after a second
}, 1000)
```

If you get any errors when you try to run this, make sure your motor is plugged in correctly.

For other motors such as the `MeduimMotor`, check the [default supported motors](http://wasabifan.github.io/ev3dev-lang-js/modules/_motors_.html) list.
Copy link
Member

Choose a reason for hiding this comment

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

Meduim -> Medium


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:
Copy link
Member

Choose a reason for hiding this comment

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

Remove "And" at the beginning of the sentence


```javascript
motor.doSomething(speed, otherArgument) // where doSomething can be replaced by any valid method.
```

You can also **reset** and **read** the position of a motor using `motor.reset()` and `motor.position`.
Copy link
Member

Choose a reason for hiding this comment

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

Keep in mind that reset resets the position and the last-used command, stop mode, etc. Resetting the position alone is motor.position = 0. To make this clear, you could do this:

You can also reset and read the position of a motor using motor.reset() and motor.position, respectively.

What you do exactly depends on what you'd like to communicate there; I'll leave that up to you.


## Sensors
Plug a ev3 color sensor into port 1, then edit `test.js` again appending this to the bottom:
Copy link
Member

Choose a reason for hiding this comment

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

EV3


```javascript
var sensor = new ev3dev.ColorSensor('in1'); // create new color sensor called 'sensor'. in1 refers to port 1

setInterval(function () {
console.log(sensor.reflectedLightIntensity); // log the reflected light percent of the sensor every 300 milliseconds
}, 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:
Copy link
Member

Choose a reason for hiding this comment

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

sensors -> sensor's

Copy link
Member

Choose a reason for hiding this comment

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

What do you think people will need to set the mode for? Properties like reflectedLightIntensity should automatically set it.


```javascript
sensor.mode = 'NEW-MODE'; // where 'NEW-MODE' can be replaced by any valid mode
```

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)
Copy link
Member

Choose a reason for hiding this comment

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

accessor (two Cs)


## 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).
Copy link
Member

Choose a reason for hiding this comment

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

Remove "So"


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)
Copy link
Member

Choose a reason for hiding this comment

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

ambientLightIntensity etc

should be

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 both really useful pages aswell.
Copy link
Member

Choose a reason for hiding this comment

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

really -> extremely

Copy link
Member

Choose a reason for hiding this comment

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

aswell -> as well