From e1b15643a3bb3346cd484a65c630acf95eb66e01 Mon Sep 17 00:00:00 2001 From: Victor Nakoryakov Date: Mon, 31 Oct 2011 19:04:08 +0400 Subject: [PATCH] + various documentation --- MIT-LICENSE.txt | 20 ++++ README.rst | 79 ++++++++++++++++ doc/quickstart.rst | 230 +++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 329 insertions(+) create mode 100644 MIT-LICENSE.txt create mode 100644 README.rst create mode 100644 doc/quickstart.rst diff --git a/MIT-LICENSE.txt b/MIT-LICENSE.txt new file mode 100644 index 0000000..51ef102 --- /dev/null +++ b/MIT-LICENSE.txt @@ -0,0 +1,20 @@ +Copyright (c) 2011 Amperka Team, http://github.com/amperka/ino + +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE +LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION +WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..eeaf147 --- /dev/null +++ b/README.rst @@ -0,0 +1,79 @@ +Ino is a command line toolkit for working with Arduino hardware. + +It allows you to: + + * Quickly create new projects + * Build a firmware from multiple source files and libraries + * Upload the firmware to a device + * Perform serial communication with a device (aka serial monitor) + +Ino may replace Arduino IDE UI if you prefer to work with command +line and an editor of your choice or if you want to integrate Arduino +build process to 3-rd party IDE. + +Ino is based on ``make`` to perform builds. However Makefiles are +generated automatically and you'll never see them if you don't want to. + +Features +======== + + * Simple. No build scripts are necessary. + * Out-of-source builds. Directories with source files are not + cluttered with intermediate object files. + * Support for ``*.pde`` and ``*.ino`` sketches as well as + raw ``*.c`` and ``*cpp``. + * Automatic dependency tracking. Referred libraries are automatically + included in the build process. Changes in ``*.h`` files lead + to recompilation of sources which include them. + * Pretty colorful output. + * Support for all boards that are supported by Arduino IDE. + * Fast. Discovered tool paths and other stuff is cached across runs. + If nothing has changed, nothing is build. + * Flexible. Support for simple ini-style config files to setup + machine-specific info like used Arduino model, Arduino distribution + path, etc just once. + +Installation +============ + +With python setup tools:: + + $ sudo pip install ino + # ... or ... + $ sudo easy_install ino + +Or clone from GitHub:: + + $ git clone git://github.com/amperka/ino.git + $ export PATH=`pwd`/ino/bin + +Requirements +============ + + * Python 2.6+ + * Arduino IDE distribution + * ``make`` and ``avr-gcc`` for building + * ``picocom`` for serial communication + +Limitations +=========== + + * As for current version, ino works only in Linux. However it was created + with other platform users in mind, so it will eventually get + cross-platform support. Help from Windows- and MacOS- developers is + much appreciated. + * Ino is not yet well tested with release candidate of upcoming Arduino 1.0 + software. Although it should be compatible. + +Getting Help +============ + + * Take a look at [Quick start tutorial]. + * Run ``ino --help``. + * Post issues to GitHub. + +License +======= + +If not stated otherwise ino is distributed in terms of MIT software license. +See MIT-LICENSE.txt in the distribution for details. diff --git a/doc/quickstart.rst b/doc/quickstart.rst new file mode 100644 index 0000000..c63dd91 --- /dev/null +++ b/doc/quickstart.rst @@ -0,0 +1,230 @@ + +Quick start +=========== + +Learn how to work with ino in few minutes. + +Creating a project +------------------ + +Let's create a simple project:: + + $ mkdir beep + $ cd beep + $ ino init -t blink + +Here we've created a new directory for our project and initialized project +skeleton with ``ino init`` command. We chose to use *blink* as a project +template. That will create a simple sketch for LED blinking on pin 13. +Lets see what we've got:: + + $ tree + . + ├── lib + └── src + └── sketch.pde + + $ cat src/sketch.pde + + #define LED_PIN 13 + + void setup() + { + pinMode(LED_PIN, OUTPUT); + } + + void loop() + { + digitalWrite(LED_PIN, HIGH); + delay(100); + digitalWrite(LED_PIN, LOW); + delay(900); + } + +Here we have two directories. ``src`` is a source directory where we can +put our project's ``*.[c|cpp|pde|h|hpp]`` source files. ``sketch.pde`` +was created for us, so we have a starting point. ``lib`` is a directory +where we may put 3-rd party libraries if we would want. + +Building +-------- + +Lets build it:: + + $ ino build + Searching for Board description file (boards.txt) ... /usr/local/share/arduino/hardware/arduino/boards.txt + Searching for Arduino core library ... /usr/local/share/arduino/hardware/arduino/cores/arduino + Searching for Arduino standard libraries ... /usr/local/share/arduino/libraries + Searching for Arduino lib version file (version.txt) ... /usr/local/share/arduino/lib/version.txt + Detecting Arduino software version ... 22 + Searching for avr-gcc ... /usr/bin/avr-gcc + Searching for avr-g++ ... /usr/bin/avr-g++ + Searching for avr-ar ... /usr/bin/avr-ar + Searching for avr-objcopy ... /usr/bin/avr-objcopy + Scanning dependencies of src + src/sketch.cpp + arduino/wiring_shift.c + arduino/wiring.c + arduino/WInterrupts.c + arduino/wiring_digital.c + arduino/wiring_pulse.c + arduino/wiring_analog.c + arduino/pins_arduino.c + arduino/HardwareSerial.cpp + arduino/WString.cpp + arduino/main.cpp + arduino/Print.cpp + arduino/WMath.cpp + arduino/Tone.cpp + Linking libcore.a + Linking firmware.elf + Converting to firmware.hex + +Whew! A lot of work has been done behind the scenes for a single command. +It's at most about finding necessary tools and directories, and compiling +the standard core library. Actually you shouldn't care. The consequence +is that we've got ``firmware.hex``—ready to upload binary file. + +Uploading +--------- + +Lets upload it:: + + $ ino upload + Searching for stty ... /bin/stty + Searching for avrdude ... /usr/local/share/arduino/hardware/tools/avrdude + Searching for avrdude.conf ... /usr/local/share/arduino/hardware/tools/avrdude.conf + + avrdude: AVR device initialized and ready to accept instructions + + Reading | ################################################## | 100% 0.00s + + avrdude: Device signature = 0x1e950f + avrdude: reading input file ".build/firmware.hex" + avrdude: writing flash (428 bytes): + + Writing | ################################################## | 100% 0.08s + + avrdude: 428 bytes of flash written + avrdude: verifying flash memory against .build/firmware.hex: + avrdude: load data flash data from input file .build/firmware.hex: + avrdude: input file .build/firmware.hex contains 428 bytes + avrdude: reading on-chip flash data: + + Reading | ################################################## | 100% 0.06s + + avrdude: verifying ... + avrdude: 428 bytes of flash verified + + avrdude: safemode: Fuses OK + + avrdude done. Thank you. + +Again, quite much output, but the job is done. Arduino flashes with its +buil-in LED on pin 13. + +Serial communication +-------------------- + +OK, now lets deal with serial communication a bit. With editor of your choice change +``src/sketch.pde`` to:: + + void setup() + { + Serial.begin(9600); + } + + void loop() + { + Serial.println(millis()); + delay(1000); + } + +This should transmit number of milliseconds spent from power up every second via +serial port. Lets build it:: + + $ ino build + Scanning dependencies of src + src/sketch.cpp + Linking firmware.elf + Converting to firmware.hex + +As you can see much fewer of steps have been performed behind the scenes. It is +because only things that have been changed are taken into account. This boosts +up the build. + +Lets upload it with ``ino upload``. When uploading is done lets connect to the +device with serial monitor to see what it prints:: + + $ ino serial + Searching for Serial monitor (picocom) ... /usr/bin/picocom + picocom v1.4 + + port is : /dev/ttyACM0 + flowcontrol : none + baudrate is : 9600 + parity is : none + databits are : 8 + escape is : C-a + noinit is : no + noreset is : no + nolock is : yes + send_cmd is : ascii_xfr -s -v -l10 + receive_cmd is : rz -vv + + Terminal ready + 0 + 1000 + 2004 + 3009 + 4014 + +That's what we want! Press Ctrl+A Ctrl+X to exit. + +Tweaking parameters +------------------- + +All examples were done in assumption that you have Arduino Uno and it is +available on default port. Now consider you have Arduino Mega 2560 and +it is available on port ``/dev/ttyACM1``. We have to specify this for +our build steps as command-line switches. + +Board model may be set with ``--board-model`` or ``-m`` switch. Port +is set with ``--serial-port`` or ``-p`` switch. So lets do it:: + + $ ino build -m mega2560 + $ ino upload -m mega2560 -p /dev/ttyACM1 + $ ino serial -p /dev/ttyACM1 + +It can be annoying to provide these switches over and over again. So +you can save them in ``ino.ini`` file in project directory. Put +following lines to the ``ino.ini``:: + + [build] + board-model = mega2560 + + [upload] + board-model = mega2560 + serial-port = /dev/ttyACM1 + + [serial] + serial-port = /dev/ttyACM1 + +Now you can build, upload and communicate via serial not having to provide +any parameters. Well, in most cases if you build for Mega 2560, you will +want to upload to Mega 2560 as well. The same about serial port setting. +So to don't repeat settings for different commands shared switches could +be moved up to an unnamed section. So having just following lines in ``ino.ini`` +is enough:: + + board-model = mega2560 + serial-port = /dev/ttyACM1 + +Furthermore, if you have Mega 2560, it is likely that you have it for all +projects you make. You can put a shared configuration file to either:: + + 1. /etc/ino.ini + 2. ~/inorc + +And it'll be used for setting default parameter values if they're not +overriden by the local ``ino.ini`` or by explicit command-line switches.