iotz - compile things easy

DISCLAIMER: I use this project for my day to day stuff and I know few other folks do the same. Concerned or have an idea? be vocal and create an issue.

in action

requirements

Install Node.js 8+ and Docker.

!! if you are on Windows, use Linux containers and share the C drive from settings.

how to install

npm i iotz -g

iotz update

You may need sudo to run the update command. Try without sudo first

usage

usage: iotz <command> [options]

A quick start with an Arduino mxchip project

iotz create arduino mxchip myproject
cd myproject
iotz init
iotz compile

or a Raspberry Pi project

iotz create raspberry hello
cd hello
iotz init
iotz make

Alternatively, you might download an online Arduino, ARMmbed, Micropython, Raspberry Pi etc. sample and build it as we did with the tests / examples under test/

see extensions and how things work

The documentation below, applies to all extensions. However, you may find some extension specific details under their README. i.e. arduino mbed raspberry

commands

help

Display available options

version

Show version (semver)

update

Update base container to latest (from Docker registry) and re-install extensions on top of it. If there is a container associated with the current folder, delete that. (force update)

You may re-install iotz via npm install -g iotz to get latest changes. Post install process will automaticall call update command.

clean

Deletes the local container for the current path. Also, cleans up the auto generated files and folders.

compile

Compile the project on given path (may need an iotz.json on path)

compile triggers a set of platform specific commands to build the project on the path. Thus, it may require both target and toolchain are defined under iotz.json file.

A successful init phase (see below) will ensure that you have iotz.json file in place.

Some platforms (extensions) do not require a particular target hence you won't see issue by not having an iotz.json file in place.

connect

connect <additional args for docker>

Runs the current container bash in an interactive mode (tty is enabled). ../<current path> is attached by default.

create

create <toolchain name> <board name> <optional project name>

Creates an empty project for given toolchain and optinally board.

i.e.

iotz create arduino yun

The command above will create a sampleApplication.ino file and iotz.json config file on the current folder. If you give a project name as shown below;

iotz create arduino yun new_project

This will create a folder named new_project and put the code and config file under it.

<toolchain name> is the name of extension. i.e. arduino, mbed, raspberry... You may find the <board name>from here

Once creation is done, you need to call iotz init on the target project folder to setup the specialized container.

export

Exports a makefile (depends to extension)

init

init <optional target board name>

Initialize a specialized container for current path.

iotz initializes a specialized container per project. init phase is required for specialization. iotz detects the extension required for the project during this phase and installs as defined by the extension itself.

Beware. If you have previously initialized iotz for a project (path), once you call it again, it will clean up the previous initialization.

run

run <cmd> <args>

Runs the <cmd> on container's bash.

i.e. iotz run ls -l

apt / apt-get / pip / npm

Use package managers. i.e. apt-get install -y wget would add wget into the current container.

iotz runs on top of Docker containers. As a result, your scripts won't change the container. i.e. iotz run apt install -y wget will work but once the execution is complete, container will be back to its' original state. So, if you want to add packages into actual image, use the commands apt, apt-get, pip, npm directly.

P.S. Use -y with apt and apt-get P.S. npm is not available by default but once you install node package via apt, npm command will update the container image going forward.

predefined extensions

  arduino <args>                           :  run arduino cli with given args
  make <args>                              :  run make command
  mbed <args>                              :  run mbed cli with given args
  raspberry                                :  shows make, cmake, and gcc gnuhf versions
  micropython

other examples

  run:
    iotz run ls -l
  make:
    iotz make
  mbed:
    iotz mbed target -S
  arduino:
    iotz arduino --install-boards AZ3166:stm32f4

iotz.json file

Introducing a yet another project file is not desirable. Yet, a basic configuration is needed to keep toolchain user from repeating entries.

A basic iotz.json file for mxchip AZ3166

{
  "toolchain": "arduino",
  "target": "mxchip",
  "filename": "sample.ino"
}

mbed nucleo l476rg with a lib

{
  "toolchain": "mbed",
  "target": "nucleo_l476rg",
  "deps":
  [
    {
      "name": "NDefLib",
      "url" : "https://developer.mbed.org/teams/ST/code/NDefLib/#31f727872290"
    }
  ]
}

WARNING: deps names are case sensitive (and optional)

toolchain: name of the extension. i.e. arduino or mbed or anything else!

target: target device name. see board names

deps: array of {name, url} pairs to defined dependencies

filename: main source code filename.

mountConfig: By default, iotz mounts from ../. If depth of the current path is 3 or more folders, iotz mounts from ../... This approach may not fit for all. So, you may use mountConfig to define a relative mount point manually. i.e. "mountConfig": "../build"

_*Depending to extension, you might have other required definitions.

F.A.Q

How to update iotz?

npm i -g iotz

Once it's complete

iotz update

You may need sudo to run the update command. Try without sudo first

where can I find the target board names

iotz doesn't control the extensions and what targets those extensions support. You will find a basic info below. Please check extension's page for better coverage.

ARM mbed target names are available from https://os.mbed.com/. Simply find your board there. On the board page, you will find the TARGET NAME for that board.

Arduino target names might be a bit more tricky to find but the list below should help for starters;

  AZ3166 MXCHIP_AZ3166 - arduino yun - arduino uno - arduino diecimila
  arduino nano - arduino mega - arduino megaADK - arduino leonardo - arduino leonardoeth
  arduino micro - arduino esplora - arduino mini - arduino ethernet - arduino fio
  arduino bt - arduino pro - arduino atmegang - arduino robotControl - arduino robotMotor
  arduino gemma - arduino circuitplay32u4cat - arduino yunmini - arduino chiwawa - arduino one
  arduino unowifi - esp8266 generic - esp8266 esp8285 - esp8266 espduino - esp8266 huzzah
  esp8266 espresso_lite_v1 - esp8266 espresso_lite_v2 - esp8266 phoenix_v1 - esp8266 phoenix_v2 - esp8266 nodemcu
  esp8266 nodemcuv2 - esp8266 modwifi - esp8266 thing - esp8266 thingdev - esp8266 esp210
  esp8266 d1_mini - esp8266 d1_mini_pro - esp8266 d1_mini_lite - esp8266 d1 - esp8266 espino
  esp8266 espinotee - esp8266 wifinfo - esp8266 arduino-esp8266 - esp8266 gen4iod - esp8266 oak

iotz arduino extension helps with the names. i.e. iotz init arduino mxchip is sufficient instead of iotz init arduino MXCHIP_AZ3166

how your project folder structure should look like?

Similar to folder structure for ARMmbed or Arduino or other.. Keep it the same! If you are just starting and don't have a particular structure, please visit their websites and see the sample projects.

You might also visit test/ folder and see by yourself. Also, see run.batch for the test commands.

how containers are managed ?

iotz creates a sub container that is tailored for your project and depend on azureiot/iotz container.

In order to benefit from docker caching, below naming is used.

aiot_iotz_ folder_ino

i.e. aiot_iotz_7396162

more info is available here

how should I clean up the containers ?

Try pruning! -> https://docs.docker.com/config/pruning/

unable to find mbed or arduino or arm-linux-gnueabihf-g++ ....

Update might possibly fix it.

Try iotz update and / or iotz clean

open preproc/ctags_target_for_gcc_minus_e.cpp: no such file or directory

Try iotz clean and then compile again

roadmap

See active list of features under development.

contributing

Please test the changes and code style (eslint) prior to sending a PR. (Running the tests may take some serious amount of time and your network traffic.)

cd test && node runtests.js

LICENSE

MIT