Skip to content

Commit e1b1564

Browse files
nkrkvnkrkv
committed
+ various documentation
1 parent 0746a44 commit e1b1564

File tree

3 files changed

+329
-0
lines changed

3 files changed

+329
-0
lines changed

‎MIT-LICENSE.txt

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
Copyright (c) 2011 Amperka Team, http://github.com/amperka/ino
2+
3+
Permission is hereby granted, free of charge, to any person obtaining
4+
a copy of this software and associated documentation files (the
5+
"Software"), to deal in the Software without restriction, including
6+
without limitation the rights to use, copy, modify, merge, publish,
7+
distribute, sublicense, and/or sell copies of the Software, and to
8+
permit persons to whom the Software is furnished to do so, subject to
9+
the following conditions:
10+
11+
The above copyright notice and this permission notice shall be
12+
included in all copies or substantial portions of the Software.
13+
14+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
15+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
16+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
17+
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
18+
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
19+
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
20+
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

‎README.rst

+79
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
Ino is a command line toolkit for working with Arduino hardware.
2+
3+
It allows you to:
4+
5+
* Quickly create new projects
6+
* Build a firmware from multiple source files and libraries
7+
* Upload the firmware to a device
8+
* Perform serial communication with a device (aka serial monitor)
9+
10+
Ino may replace Arduino IDE UI if you prefer to work with command
11+
line and an editor of your choice or if you want to integrate Arduino
12+
build process to 3-rd party IDE.
13+
14+
Ino is based on ``make`` to perform builds. However Makefiles are
15+
generated automatically and you'll never see them if you don't want to.
16+
17+
Features
18+
========
19+
20+
* Simple. No build scripts are necessary.
21+
* Out-of-source builds. Directories with source files are not
22+
cluttered with intermediate object files.
23+
* Support for ``*.pde`` and ``*.ino`` sketches as well as
24+
raw ``*.c`` and ``*cpp``.
25+
* Automatic dependency tracking. Referred libraries are automatically
26+
included in the build process. Changes in ``*.h`` files lead
27+
to recompilation of sources which include them.
28+
* Pretty colorful output.
29+
* Support for all boards that are supported by Arduino IDE.
30+
* Fast. Discovered tool paths and other stuff is cached across runs.
31+
If nothing has changed, nothing is build.
32+
* Flexible. Support for simple ini-style config files to setup
33+
machine-specific info like used Arduino model, Arduino distribution
34+
path, etc just once.
35+
36+
Installation
37+
============
38+
39+
With python setup tools::
40+
41+
$ sudo pip install ino
42+
# ... or ...
43+
$ sudo easy_install ino
44+
45+
Or clone from GitHub::
46+
47+
$ git clone git://github.com/amperka/ino.git
48+
$ export PATH=`pwd`/ino/bin
49+
50+
Requirements
51+
============
52+
53+
* Python 2.6+
54+
* Arduino IDE distribution
55+
* ``make`` and ``avr-gcc`` for building
56+
* ``picocom`` for serial communication
57+
58+
Limitations
59+
===========
60+
61+
* As for current version, ino works only in Linux. However it was created
62+
with other platform users in mind, so it will eventually get
63+
cross-platform support. Help from Windows- and MacOS- developers is
64+
much appreciated.
65+
* Ino is not yet well tested with release candidate of upcoming Arduino 1.0
66+
software. Although it should be compatible.
67+
68+
Getting Help
69+
============
70+
71+
* Take a look at [Quick start tutorial].
72+
* Run ``ino --help``.
73+
* Post issues to GitHub.
74+
75+
License
76+
=======
77+
78+
If not stated otherwise ino is distributed in terms of MIT software license.
79+
See MIT-LICENSE.txt in the distribution for details.

‎doc/quickstart.rst

+230
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,230 @@
1+
2+
Quick start
3+
===========
4+
5+
Learn how to work with ino in few minutes.
6+
7+
Creating a project
8+
------------------
9+
10+
Let's create a simple project::
11+
12+
$ mkdir beep
13+
$ cd beep
14+
$ ino init -t blink
15+
16+
Here we've created a new directory for our project and initialized project
17+
skeleton with ``ino init`` command. We chose to use *blink* as a project
18+
template. That will create a simple sketch for LED blinking on pin 13.
19+
Lets see what we've got::
20+
21+
$ tree
22+
.
23+
├── lib
24+
└── src
25+
└── sketch.pde
26+
27+
$ cat src/sketch.pde
28+
29+
#define LED_PIN 13
30+
31+
void setup()
32+
{
33+
pinMode(LED_PIN, OUTPUT);
34+
}
35+
36+
void loop()
37+
{
38+
digitalWrite(LED_PIN, HIGH);
39+
delay(100);
40+
digitalWrite(LED_PIN, LOW);
41+
delay(900);
42+
}
43+
44+
Here we have two directories. ``src`` is a source directory where we can
45+
put our project's ``*.[c|cpp|pde|h|hpp]`` source files. ``sketch.pde``
46+
was created for us, so we have a starting point. ``lib`` is a directory
47+
where we may put 3-rd party libraries if we would want.
48+
49+
Building
50+
--------
51+
52+
Lets build it::
53+
54+
$ ino build
55+
Searching for Board description file (boards.txt) ... /usr/local/share/arduino/hardware/arduino/boards.txt
56+
Searching for Arduino core library ... /usr/local/share/arduino/hardware/arduino/cores/arduino
57+
Searching for Arduino standard libraries ... /usr/local/share/arduino/libraries
58+
Searching for Arduino lib version file (version.txt) ... /usr/local/share/arduino/lib/version.txt
59+
Detecting Arduino software version ... 22
60+
Searching for avr-gcc ... /usr/bin/avr-gcc
61+
Searching for avr-g++ ... /usr/bin/avr-g++
62+
Searching for avr-ar ... /usr/bin/avr-ar
63+
Searching for avr-objcopy ... /usr/bin/avr-objcopy
64+
Scanning dependencies of src
65+
src/sketch.cpp
66+
arduino/wiring_shift.c
67+
arduino/wiring.c
68+
arduino/WInterrupts.c
69+
arduino/wiring_digital.c
70+
arduino/wiring_pulse.c
71+
arduino/wiring_analog.c
72+
arduino/pins_arduino.c
73+
arduino/HardwareSerial.cpp
74+
arduino/WString.cpp
75+
arduino/main.cpp
76+
arduino/Print.cpp
77+
arduino/WMath.cpp
78+
arduino/Tone.cpp
79+
Linking libcore.a
80+
Linking firmware.elf
81+
Converting to firmware.hex
82+
83+
Whew! A lot of work has been done behind the scenes for a single command.
84+
It's at most about finding necessary tools and directories, and compiling
85+
the standard core library. Actually you shouldn't care. The consequence
86+
is that we've got ``firmware.hex``—ready to upload binary file.
87+
88+
Uploading
89+
---------
90+
91+
Lets upload it::
92+
93+
$ ino upload
94+
Searching for stty ... /bin/stty
95+
Searching for avrdude ... /usr/local/share/arduino/hardware/tools/avrdude
96+
Searching for avrdude.conf ... /usr/local/share/arduino/hardware/tools/avrdude.conf
97+
98+
avrdude: AVR device initialized and ready to accept instructions
99+
100+
Reading | ################################################## | 100% 0.00s
101+
102+
avrdude: Device signature = 0x1e950f
103+
avrdude: reading input file ".build/firmware.hex"
104+
avrdude: writing flash (428 bytes):
105+
106+
Writing | ################################################## | 100% 0.08s
107+
108+
avrdude: 428 bytes of flash written
109+
avrdude: verifying flash memory against .build/firmware.hex:
110+
avrdude: load data flash data from input file .build/firmware.hex:
111+
avrdude: input file .build/firmware.hex contains 428 bytes
112+
avrdude: reading on-chip flash data:
113+
114+
Reading | ################################################## | 100% 0.06s
115+
116+
avrdude: verifying ...
117+
avrdude: 428 bytes of flash verified
118+
119+
avrdude: safemode: Fuses OK
120+
121+
avrdude done. Thank you.
122+
123+
Again, quite much output, but the job is done. Arduino flashes with its
124+
buil-in LED on pin 13.
125+
126+
Serial communication
127+
--------------------
128+
129+
OK, now lets deal with serial communication a bit. With editor of your choice change
130+
``src/sketch.pde`` to::
131+
132+
void setup()
133+
{
134+
Serial.begin(9600);
135+
}
136+
137+
void loop()
138+
{
139+
Serial.println(millis());
140+
delay(1000);
141+
}
142+
143+
This should transmit number of milliseconds spent from power up every second via
144+
serial port. Lets build it::
145+
146+
$ ino build
147+
Scanning dependencies of src
148+
src/sketch.cpp
149+
Linking firmware.elf
150+
Converting to firmware.hex
151+
152+
As you can see much fewer of steps have been performed behind the scenes. It is
153+
because only things that have been changed are taken into account. This boosts
154+
up the build.
155+
156+
Lets upload it with ``ino upload``. When uploading is done lets connect to the
157+
device with serial monitor to see what it prints::
158+
159+
$ ino serial
160+
Searching for Serial monitor (picocom) ... /usr/bin/picocom
161+
picocom v1.4
162+
163+
port is : /dev/ttyACM0
164+
flowcontrol : none
165+
baudrate is : 9600
166+
parity is : none
167+
databits are : 8
168+
escape is : C-a
169+
noinit is : no
170+
noreset is : no
171+
nolock is : yes
172+
send_cmd is : ascii_xfr -s -v -l10
173+
receive_cmd is : rz -vv
174+
175+
Terminal ready
176+
0
177+
1000
178+
2004
179+
3009
180+
4014
181+
182+
That's what we want! Press Ctrl+A Ctrl+X to exit.
183+
184+
Tweaking parameters
185+
-------------------
186+
187+
All examples were done in assumption that you have Arduino Uno and it is
188+
available on default port. Now consider you have Arduino Mega 2560 and
189+
it is available on port ``/dev/ttyACM1``. We have to specify this for
190+
our build steps as command-line switches.
191+
192+
Board model may be set with ``--board-model`` or ``-m`` switch. Port
193+
is set with ``--serial-port`` or ``-p`` switch. So lets do it::
194+
195+
$ ino build -m mega2560
196+
$ ino upload -m mega2560 -p /dev/ttyACM1
197+
$ ino serial -p /dev/ttyACM1
198+
199+
It can be annoying to provide these switches over and over again. So
200+
you can save them in ``ino.ini`` file in project directory. Put
201+
following lines to the ``ino.ini``::
202+
203+
[build]
204+
board-model = mega2560
205+
206+
[upload]
207+
board-model = mega2560
208+
serial-port = /dev/ttyACM1
209+
210+
[serial]
211+
serial-port = /dev/ttyACM1
212+
213+
Now you can build, upload and communicate via serial not having to provide
214+
any parameters. Well, in most cases if you build for Mega 2560, you will
215+
want to upload to Mega 2560 as well. The same about serial port setting.
216+
So to don't repeat settings for different commands shared switches could
217+
be moved up to an unnamed section. So having just following lines in ``ino.ini``
218+
is enough::
219+
220+
board-model = mega2560
221+
serial-port = /dev/ttyACM1
222+
223+
Furthermore, if you have Mega 2560, it is likely that you have it for all
224+
projects you make. You can put a shared configuration file to either::
225+
226+
1. /etc/ino.ini
227+
2. ~/inorc
228+
229+
And it'll be used for setting default parameter values if they're not
230+
overriden by the local ``ino.ini`` or by explicit command-line switches.

0 commit comments

Comments
 (0)