Evothings Studio Starter Guide

Here we have collected everything you need to get started with creating mobile apps for the Internet of Things in JavaScript/HTML using Evothings Studio 2.0.

Evothings Studio 2.0 in a nutshell

Evothings Studio is a development tool for creating mobile applications for the Internet of Things (IoT). Evothings Studio is based on web technologies and open-source software components.

Please note that this guide applies to Evothings Studio 2.0 Beta. Version 2.0 is an improvement over version 1.2 in many ways, most notably the connection between Evothings Workbench and Evothings Viewer is more reliable and flexible. (Evothings Viewer replaces the Evothings Client app used with Evothings Studio 1.2.)

Here are the tools you use to develop apps with Evothings Studio:

  • Evothings Viewer – Mobile application that runs any apps written in HTML/JavaScript (install it from the app stores). Connect from the Viewer app to the Workbench, and get live reloading of all the apps you are working on.
  • Evothings Workbench – Use the Workbench to run apps in Evothings Viewer. It runs on your laptop or desktop machine, next to your code editor. The Workbench features a visual user interface, example apps, a launchpad for your app projects, automatic live reload on file save, logging and code evaluation tools. Evothings Workbench comes bundled with the Evothings Studio download.
  • Your favorite text editor or IDE code editor (not included with the Evothings Studio download). When you press save in the editor, Evothings Workbench will notice the updated file and trigger a reload of your app running in Evothings Viewer. This enables a fast development workflow.

workbench-client-evothings

With Evothings Studio you have the freedom to use any code editor you like. As soon as you save a file, changes will be picked up by Evothings Workbench and connected mobile devices will be notified to update the running app. The live reload mechanism works with all files and formats. For example, if you save a bitmap image in Photoshop, the app will update itself and display the new image.

To make it easy to get started, Evothings Workbench comes with a collection of ready-to-use example apps for various IoT devices, for example Eddystone and iBeacon beacons, Arduino, TI SensorTag, and many more.

What you need

Here is a list of what you need to get going:

  • Laptop/desktop machine running Windows, OS X or Linux.
  • Mobile phone or tablet running iOS (iOS 7 or later) or Android (to use Bluetooth Low Energy you need a device with Bluetooth 4.0 or later running Android 4.3 or later).
  • Download Evothings Studio - Install Evothings Workbench by unzipping the download package on your laptop or desktop machine.
  • Install Evothings Viewer - Get it from Apple App Store or Google Play.
  • To run the example apps that come with Evothings Studio, you need the hardware used by each example; such as Arduino, beacons, TI SensorTag, or LightBlue Bean (see the examples documentation for further details). There are also examples that work out-of-the box with no special hardware, like the Cordova Accelerometer and BLE Scan examples.
  • To build native apps, you need the open-source Apache Cordova build system.

coffee-stains

Getting started guide

First time step-by-step guide

Here is a step-by-step guide to get you going, right from scratch:

  • Download Evothings Studio to your computer (the download contains Evothings Workbench).
  • Install Evothings Viewer on your mobile phones and tablets.
  • Start Evothings Workbench.
  • Launch Evothings Viewer.
  • Get a connect code in the Workbench by clicking "Get Code" under the Connect tab.
  • Connect to the Workbench from the phone by entering the connect code.
  • In the Workbench, press the RUN button on the “Hello World” example.
  • Done! You have now run your first app using Evothings Studio.

How to edit code

Next step is to modify the example code:

  • Press the COPY button on the “Hello World” example. This will make a copy of the app and it will appear under the "My Apps" tab.
  • Press RUN to launch the app on your connected phone or tablet. Pressing RUN makes the app the currently active app. The active app is watched for code changes and when a file is changed the app is automatically reloaded on connected devices. This is like RUN being pressed automatically for you!
  • Press the CODE button on your “Hello World” app under "My Apps". This will open the system file browser for the app files.
  • To see live reload in action, open the index.html file in a text editor. You can use your favourite editor or IDE.
  • Make some interesting changes to the code – e.g. modify the h1 heading to say "Hello Evothings".
  • Save the file (typically press CTRL+S).
  • Done! The app now automatically reloads in the Viewer – changes are instantly visible.

Create your own project

To create your own mobile application project, you have three options:

  • Click the NEW button. This will give you a blank app skeleton.
  • Click the COPY button on an example app. You can then modify the app and continue from there.
  • Drag the any HTML file to the Evothings Workbench window.

All of the above methods will create an entry under the tab "My Apps". You can rearrange app entries using drag and drop. Close them using the close icon (x). This will not remove the files on disk.

When you create an app using NEW or COPY, the app files will be saved in a folder on disk. You can specify the folder in a dialog box. If you wish to move the app to another folder, delete the app item under "My Apps" (will not delete the app folder). Move the app folder to the new location. Drag index.html from the system file browser into "My Apps".

To create an app from scratch (or add an existing app you have) follow these steps:

  • Create a folder with the project files (HTML/CSS/JavaScript/media files).
  • There needs to be at least one HTML file in the project – used as the entry point of the app.
  • Drag the main HTML file, e.g. the index.html, into the list of apps in Evothings Workbench.
  • Now just press RUN on the app to launch it in the Viewer.
  • Note that you can connect multiple mobile phones and tablets to Evothings Workbench. When you save any file in the project (or press RUN), the app will reload on all of them!

An Evothings app project is just a folder with your HTML and JavaScript files. Just like any web site. And as soon as anything is changed, the Workbench pushes it to all connected viewers, just like that!

Workbench settings

In the "More" menu you will find the "Settings" menu option. This open a dialog where you can change the font size used in the Tools window, and the number of directory levels traversed by the reload file watcher. You can also change the default path to the folder used by the NEW and COPY buttons.

The setting for the reload server address is intended for developers of Evothings Studio. In most cases you should not change this value. Default value is "https://deploy.evothings.com". The reload server handles the communication between Evothings Workbench and connected phones and tablets.

Useful background knowledge

The documentation pages contains information about the tools available in Evothings Studio.

Apache_Cordova1Apache Cordova is a build system for creating native apps developed in HTML/JavaScript. You can use Evothings Studio without Cordova, but if you want to create native apps it is needed.

It is useful to know that Evothings Viewer itself is a Cordova app, developed using Evothings Studio.

Cordova plugins are code modules that provides native device functionality, such as Bluetooth Low Energy and iBeacon ranging. Evothings Viewer comes with a number of plugins preinstalled.

Overview of the Evothings Studio download

Included with the Evothings Studio download:

  • Evothings Workbench desktop application
  • Example apps
  • Documentation is available online at: evothings.com/doc

Note that Evothings Viewer is installed from the app stores, and is not included with the download.

Evothings Workbench runs on top of the nw.js engine (which includes WebKit and node.js). The nw.js binary is included with the download (named "EvothingsWorkbench"). All download packages (Windows/OS X/Linux) are basically identical except for the node-webkit binary.

Here is an overview of some of the files and folders in the unzipped download package:

examples - example apps
hyper - JavaScript code for the Workbench
  server - code that communicates with the proxy server that routes reloads to the Viewer
  settings
    settings.js - settings you can modify
  ui - user interface code
node_modules - modules used by node-webkit
package.json - Workbench application settings

Goodies

evothings-studio-illustration

Evothings Studio gives you several useful tools and goodies:

  • Develop on multiple mobile devices simultaneously - test your app on iOS and Android phones and tablets at the same time
  • Run an app on all connected devices with one click
  • When saving a file all connected devies reload the running app - you get to see the result instantly
  • Freedom to use any editor (live reload works with all editors that save data in HTML/JS/CSS/media files, also HTML editors and image editors)
  • Quickly get started with your own apps copying code from the example apps (code for examples included with the download)
  • Easily send log data from connected devices
  • Evaluate JavaScript code interactively on connected devices, useful for both development and debugging
  • Build native apps using Apache Cordova - no proprietary tools needed, include any Cordova plugins you like
  • Use live reload, logging and interactive code evaluation with any Cordova app - this makes it fast to develop and debug Cordova applications
  • Full source code is available on GitHub (Apache open source licence)

How live reload works

To learn more about how reload-on-save works, read the article Hybrid app development made fast (kindly note that this article is not updated for Evothings Studio 2.0, but basic principles still apply).

Deployment options

To let others test your app, you have the following alternatives available:

  • Apache Cordova - Build a native app with the Cordova build system. Use the exact same code base as when developing with Evothings Studio.
  • Evothings Viewer - Place your app code (HTML/CSS/JS) on a web server and run in Evothings Viewer. Just ask users to get Evothings Viewer and enter the URL to the app in the connect text box. Evothings Workbench is not needed in this case.
    Read more about how to share your app.
  • Evothings Studio - In case the other person has Evothings Studio installed you can just send the source code for the app, e.g. in a zip file, or publish it on GitHub.

How to build native apps

The Cordova IoT Starter Guide contains information about how to get going with building native apps using Cordova.

Also check out the Build overview and the Cordova Guide in the Evothings documentation.

Here’s how to build apps using Adobe’s build service for hybrid apps called Phonegap Build, just follow the instructions in this technical tutorial on preparing and uploading files.

Debugging tricks and tips

Use the Tools window in Evothings Workbench to write log messages using the hyper.log() function.

Click the "Tools" button in the Workbench menu bar to open this window. Log messages are displayed in the bottom pane.

This will log the current window width for all connected viewers:

hyper.log('window width: ' + window.innerWidth)

And this will log the device name and platform (note that the app must include cordova.js for the device object to be available):

hyper.log('device model: ' + device.model +
    ' platform: ' + device.platform)

In the top pane of the Tools window you can interactively evaluate JavaScript code on connected devices. This is useful both when developing and debugging an app.

Initially, the top pane contains some code examples you can try out. In case you have erased the initial contents, click the "Restore" button to get it back.

When you quit Evothings Workbench the contents of the top pane of the Tools window is saved automatically.

JavaScript libraries

One good thing to know is how JavaScript libraries are used. JavaScript library files are included in an app using HTML script tags (typically this is done in index.html).

There are two kinds of JavaScript libraries used in a Cordova-based mobile app (such as Evothings Viewer):

  • Cordova libraries
  • JavaScript frameworks and application libraries

Knowing the differences between these are helpful.

Cordova Libraries

Cordova libraries are bundled with the app. You never see the JavaScript plugin files in your own application code. If you wish to browse the source code for a plugin, you have to look in the plugin code, which is available in the plugin code repository (usually on GitHub), and in the native project build with Cordova.

Cordova libraries are included with one single script tag including cordova.js:

<script src="cordova.js"></script>

This will in turn include the JavaScript code for all plugins installed in the app.

JavaScript Frameworks and Application Libraries

These are libraries used by the application. The JavaScript code for other libraries must either be included with the app and loaded via script tags, or loaded from the network using script tags. However, when loading scripts over the network, the mobile device must be online to work, which may not always be the case. It is recommended that all scripts used are included with the app.

Evothings JavaScript Libraries

Evothings example applications use several JavaScript libraries related to IoT. These are included in the folder "libs/evothings" with subdirectories.

The file "libs/evothings/evothings.js" contains functions for loading scripts asynchronously, which can be useful in some circumstances.

Note that not all example apps have all libraries included, only the libraries actually used are included with each app. All Evothings libraries available can be found on GitHub.

Useful links

Get started in 5 minutes

Download Evothings Studio and experience the joy of developing mobile apps for IoT using friendly tools and a fast workflow.

It is fun and easy to get up and running!