evothings / evothings-examples

Examples for Evothings Studio.

Examples for Evothings Studio

NOTE: These examples are normally used from within the Evothings Studio where you just click the COPY button on one of the listed examples. You are not meant to clone this repo!

Instructions

The following is for developers of Evothings Studio. If you just want to use an example, they are available from the Example list inside Evothings Studio.

• For versions older than 2.1.0-alpha6 all the example apps are included in the Evothings Studio download.
• For version 2.1.0-alpha6 and forward all example apps are hosted online at Evothings.com and are downloaded on demand.

From within Evothings Studio there is no real difference in user experience, but it means we can now push out new examples (and fixes) live without a new release of Evothings Studio.

Branches

This also means we use a branch per major.minor version of Evothings Studio, so all examples valid for Evothings Studio 2.1.x is found in the 2.1 branch. Master is the ongoing work which periodically is merged into the version specific branches.

Folder structure

Apps in folder experiments are under development and are not guaranteed to work. They are also not listed in the Evothings Workbench.

Apps in folder examples are maintained and have been verified to work. They are listed in the examples tab inside Evothings Workbench.

Library files

Library files used by the example apps are included in the examples themselves but we maintain them in the repository evothings-libraries.

Build script

If you wish to build the files for hosting use the bash script build.sh. This script copies the apps from 'examples', zips them each and constructs a concatenated JSON file from all evothings.json metadata files found in the examples.

Documentation

Documentation for the applications is currently maintained in a separate repo. It is also branched per version of Evothings, here is the hosted examples documentation for Evothings Studio 2.1.x.

It is quick and fun to get started with Evothings Studio

Download Evothings Studio and be up and running with mobile IoT apps in minutes!

evothings-examples's Issues

Implement autodiscovery of Arduino WiFi shield.

Broadcast UDP packets with Cordova chrome.socket. An Arduino running the example's Arduino code should reply. Code from ETC's autodiscovery feature can be re-used for the client.

Update BLE examples to use new JavaScript API

The BLE plugin API has been updated, and the following examples need updating:

• BLE Discovery
• BLE TI SensorTag
• Arduino BLE

Details of API changes are found here: evothings/cordova-ble#14

Test Arduino LED On/Off WiFi through instructions

Test the Arduino LED On/Off WiFi example app by following its instructions.

Test Arduino LED Blink WiFi through instructions

Test the Arduino LED Blink WiFi example app by following its instructions.

TI SensorTag Sensors does not work properly on Nexus 7

Problem: There are issues with TI SensorTag Sensors on Nexus 7, because the Nexus 7 only reports devices found during scan once. The logic in the example app is written in a faulty way that assumes each device reported continuously.

Solution: Rewrite application logic.

ble-discovery shows same services when browsing multiple devices

Steps to reproduce:

1. Have at least 2 BLE devices discoverable by the client device.
2. Run the ble-discovery example and let the BLE devices be found.
3. Choose one of the devices to list its services.
4. Press the back button to go back to the list of discovered devices.
5. Choose another device to list its services.

Expected result:
The services for the second device are listed.

Actual result:
The services from the first chosen device are again listed.

BLE Discovery issues

Issues found in example BLE Discovery:

• On Nexus 7 devices are discovered, but when selecting a device Services list is empty.
• On iPhone services are displayed, but since the UUIDs are very long it is not possible to see most of the names and values (e.g. device name on main page).
• The source code is hard to read, long lines, hard to understand short variable names, no comments. See this issue #38

Problem with missing back button has been fixed, back button is added to header bar in this commit/pull request:
#45

Script that copies shared files to examples

To make the examples easy to modify and build with Cordova, make each example self-contained (like a "mini-website"). Problem is how to handle shared files. Solution is to have no copies in this repository, and have a build script that copies the files to each example.

Tasks:

• Structure the shared folder into ui files and lib files
• Write Ruby script that copies the files needed to all examples (do not copy all files, only the ones needed for each example)
• Update README.md with instructions and a design description to make it easy to understand the design choices and the file structure.

UUIDs in BLE Scan can be confused with iBeacon UUIDs

Got report from a user that BLE Scan UUIDs do not match the actual iBeacon UUIDs.

The UUIDs in BLE Scan should be removed, since they apparently cause confusion.

Reloading doesn't work in desktop browser due to BLE missing.

The easy-ble.js library causes reloading to fail if BLE is missing, e.g. when the app is being run in a desktop browser.

Steps to reproduce:

1. Launch the Arduino LED On/Off BLE example app in a desktop browser through the workbench.
2. Run another project from the workbench.

Actual results:
Reloading fails and the following error message is output to the workbench log:
"Uncaught ReferenceError: evothings is not defined [easy-ble.js: 63"

Light Demo: More pedagogical button name for "connect"

When already connected, a press on connect is not necessary. Suggest to call it "activate" or "enable" would be better.

Improve and correct UI of TI SensorTag Sensors

The UI of the "TI SensorTag Sensors" example app is not consistent with the other example apps. Correct this by for example using appropriate, style-associated markup.

Add back button to examples

Problem:

When running examples e.g. from a page gallery on web server, there is a need to be able to go back to the gallery page. On iOS this does not work, because there is no back button built in in iOS devices. (Works on Android because there we have a system back button.)

This means the user has to terminate and restart the app (Evo Client) each time she wants to go back!

Solution:

Add a back button to each of the examples.

code fix for littleEndianToUint8

Existing -

funs.littleEndianToUint8 = function(data, offset)
    {
        return data[offset];
    };

the data comes in sign extended, and should be removed

funs.littleEndianToUint8 = function(data, offset)
    {
        return 0xff & data[offset];
    };

Rename minified jquery.js to jquery.min.js

When searching the repository's files' contents, it's desirable to filter out minified files. For this reason and for clarity, the resources/libs/jquery/jquery.js file should be renamed to jquery.min.js.

Add feedback of whether TI SensorTag was found (alert if it was not found)

Additionally it's suggested to show "Scan again" button to try to search for devices and connect again.

Test Arduino BLE through instructions

Test the Arduino BLE example app by following its instructions.

Improve JSDoc in EasyBLE

Functions in easyble.js are not fully documented. Parameters and examples should be added to JSDoc comments.

EasyBLE: Make UUIDs case insensitive

Problem report from tester:

Function readServices is case sensitive for the UUIDs. For example, this does not work:

'713D0000-503E-4C75-BA94-3148F18D941E'

But this works:

'713d0000-503e-4c75-ba94-3148f18d941e'

Analysis and solution:

This is likely because the native side is reporting UUIDs in lower case. Should affect UUIDs also for characteristics and descriptors.

A solution is to lower-case UUID strings in the functions that accept UUIDs.

Suggested to have splash screen for "confusing apps"

Some apps need a further info text in the form of a splash screen; e.g.
"this apps requires the TI Sensor tag"
"this is a companion app for the BLE On/Off example"
"this app needs an external gps"
et cetera when required. We don't want people to run an app,
nothing happens and in worst case they'd walk away

BLE fails after reload

Test Arduino LED On/Off TCP read example

The example Arduino LED On/Off TCP did not have support for read (digitalRead and analogRead). Code for this have been added but is untested.

Code added in this commit:

a6379f2

Code for example app is here (note that pin values need to be adjusted for the sketch used):

https://github.com/evothings/EvoThingsExamples/blob/master/examples/arduino-led-onoff-tcp/app/index_with_read_functions.html

File arduino.js is updated:

https://github.com/evothings/EvoThingsExamples/blob/master/examples/arduino-led-onoff-tcp/app/arduino.js

The .ino files are also updated.

Create menu and documentation page.

In those examples having documentation make a menu alternative for showing a separate page with documentation. Move the documentation contents to that page.

Layout problems on iPhone 5

On iPhone 5 running iOS 7.1 the following layout problems are observed.

Titlebar and layout grows when device is rotated:

• Put device in portrait.
• Run example "Hello World".
• Rotate to landscape.
• Rotate back to portrait.
• Title bar and font size are now bigger.
• Expected behaviour is for the layout to keep its original size.

Titlebar is offset when running example "Arduino LED On/Off TCP":

• Put device in portrait.
• Run example "Arduino LED On/Off TCP".
• When connecting, the titlebar is offset so that there is a white horizontal space on top of the screen. Titlebar keeps its height however (does not scale).
• Then, rotate to landscape and back.
• Now titlebar and font size are bigger (as on the Hello World example).
• Expected behaviour is for the titlebar to not offset and maintain its size when device is rotated.

Add failure message and add "start scan" button after discovery of Arduino fails.

If the Arduino BLE Shield fails to be discovered at startup, display an error message and then show a button that when pressed restarts the discovery process.

TI SensorTag - error log message in easy-ble.js

Spotted the following error log when running TI SensorTag example. Think this occurred after pressing Start, during the connection process:

LOG: [ERR] TypeError: 'undefined' is not a function (evaluating 'win()') [easy-ble.js: 390]
LOG: [ERR] TypeError: 'undefined' is not a function (evaluating 'win()') [easy-ble.js: 390]
LOG: [ERR] TypeError: 'undefined' is not a function (evaluating 'win()') [easy-ble.js: 367]
LOG: [ERR] TypeError: 'undefined' is not a function (evaluating 'win()') [easy-ble.js: 367]
LOG: [ERR] TypeError: 'undefined' is not a function (evaluating 'win()') [easy-ble.js: 367]
LOG: [ERR] TypeError: 'undefined' is not a function (evaluating 'win()') [easy-ble.js: 367]

Test BLE Discovery through instructions

Test the BLE Discovery example app by following its instructions.

Show notification for examples that require Evothings Client when e.g. running it in a desktop browser

When launching an app that requires Cordova and cordova is missing, display an alert with message "This example needs to run in the Evothings Client (available on App Store and Google Play)".

Implement this using the cordova event "deviceready" (or whateveer it is called) and set a timeout. When timeout triggers, if the cordova deviceready event has not fired, then display the alert. Alternatively find some other way of detecting whether Cordova is present or not.

Enhancements for Arduino LED On/Off TCP

Issue description in Swedish from the original reporter:

"Vi utgick från Led on/off tcp exemplet.

Det saknades någon form av indikator på att jag var uppkopplad mot Arduinon i gränssnittet.

För Arduinon kommer kommer det vara viktigt att kunna "toggla" en pinne. Då skulle man vilja ha en knapp som skickar kommandot och dessutom lyssnar på svaret och uppdaterar sitt tillstånd därefter. Så att man hela tiden har ett GUI som är synkat mot Arduinon.

När man har skickat ett kommando vore det också bra med någon overlay som visar att kommandot skickats och att man väntar på svar, igår skickade vi lite i blindo."

arduino-wifi connection timeout

After sucessfully using either of the arduino-led-*-wifi examples to control the Arduino, if without activity waiting for a few minutes the connection drops and the Arduino's WiFi connection has to be re-established.

New BLE examples for LED On/Off

Having very basic Arduino examples is very useful to get started.
The basic LED On/Off eample exists for WiFi, but there should also be versions for Ethernet and BLE.

That would make for three examples in total:

• arduino-led-onoff-wifi (existing)
• arduino-led-onoff-ethernet (new)
• arduino-led-onoff-ble (new)

By having all connection methods covered by basic example, it becomes easy for a new developer to find and get started using the particular communication hardware she or he has access to.

It is also informative to have the exact same example for studying and learning how to use different communication technologies.

Test Hue Lights through instructions

Test the Hue Lights example app by following its instructions.

Add the drop-down menu to all examples

Add the drop-down menu to all examples. This can probably be done by just removing the now out-commented menu button from all examples. Look in EvoThingsClient gallery.html for an example of the newest HTML implementation of the menu button.

ble-scan example not updating ranges for nexus 7

Hi, I am depending on cordova-ble for an app, and I was shocked to see that my app isn't working on a Nexus 7 device. The device was using an older version of Android. I think it was 4.3.3 or something like that. I updated the device to Android 5.0.2, and it is still having issues. I downloaded this repo and tossed the ble-scan example onto the device, and I can see the exact same problem I was having.

When you start the app, the app will find all of the beacons available and display their range, but it will not update the range figures afterward. You have to either press the "STOP SCAN" button or click the bottom right menu button for Android to display all apps, and then select the Evothings ble-scan app for it to refresh the range figures.

This is kind of a big deal, and I am willing to help however I can.

Standardise UI and move example docs to separate page tab.

Make the UI of the example apps look the same as the first page of the EvoThings Client, having e.g. a bar at the top with the title and a button for showing additional info (e.g. documentation).

Add visual feedback of missing BLE capability.

In the examples requiring a device with BLE capability, provide feedback when the device is missing this required functionality, in the form of e.g. a dialog or inline error message.

arduino-led-*-wifi examples shows 2 connectivity alerts

When the arduino-led-*-wifi example apps fails to connect to the Arduino, an alert box is shown 2 times. Avoid this through e.g. introducing more error codes and improve error handling through use of these.

BLE Discovery code cleanup

I find the code hard to understand, variables like p, s, ss, si, �c, cc, ci etc are difficulty to grasp and remember. Dictionary keys would also be easier to understand if given meaningful names.

BLE code examples - use of ble_set_name() for discovery

a number of the examples hard code "BLE Shield" for the name of the BLE device to discover; this causes many issues when trying to connect to multiple BLE shields or a device that doesn't have that broadcast name. we should do the following:

a) define a unique name to each example
b) use the ble_set_name("{name}"); function in arduino
c) use the "{name}" in the appropriate JavaScript examples

there is a limitation of 10 characters to the name of a BLE service with the arduino libraries.

Missing file arrow_right_with_margin.svg

First mentioned in commit a04ecd4, the file arrow_right_with_margin.svg has never been added to this repository.

Does it have a purpose, or can the reference to it, in evothings-app.css, be safely deleted?

Update iBeacon Scan for iOS 8

To work on iOS 8 an iBeacon permission request must be made. Following JavaScript code needs to be added:

cordova.plugins.locationManager.requestAlwaysAuthorization();

or:

cordova.plugins.locationManager.requestWhenInUseAuthorization();

This displays a dialog box where the user can say yes/no.

On iOS 7 this works transparently (no dialog displayed).

Task is to update the example iBeacon Scan with the above line.

Test BLE TI SensorTag through instructions

Test the BLE TI SensorTag example app by following its instructions.

Remove usused code from arduinoledonoffble.ino

The following lines in arduinoledonoffble.ino are not used from what I can see:

Line 11:

#define INPUT_PIN A0

Lines 28-29:

// Writing to an analog input pin sets baseline for later input.
digitalWrite(INPUT_PIN, HIGH);

We should consider the LED to be off when the app sketch loads. Then the user gets a good experience when the LED goes on when using the example app. To do this we would remove these lines 43-44:

// Turn on LED.
digitalWrite(LED_PIN, HIGH);

Merge forks

Task is to merge forks that should be merged:

https://github.com/evothings/EvoThingsExamples/network

Correct HSB-HSL conversion in hue-lights.

The conversion from HSB to HSL colorspace is incorrect. Use e.g. the following resources to correct the conversion algorithm:

http://en.wikipedia.org/wiki/HSL_and_HSV
http://ariya.blogspot.se/2008/07/converting-between-hsl-and-hsv.html
http://stackoverflow.com/questions/3423214/convert-hsb-color-to-hsl

(The HSL-value is used for the CSS color of the lights color buttons in the example.)

Alert the user if Cordova native is missing, advise ETC install.

Simply detect whether e.g. onDeviceReady doesn't fire and alert the user that Cordova native is missing and that EvoThings Client should be installed.

Add Arduino "scripting library" for BLE

For Arduino TCP (WiFi/Ethernet) there is a "scripting library" that allows to set pin mode and write/read pins from JavaScript, with no modifications needed in the Arduino code.

This would be great to have also for BLE, as it simplifies writing BLE apps for Arduino.

Add visual feedback to BLE device discovery action.

Add visual feedback to the device discovery action in the form of e.g. a graphical animation or a text message. A text message could e.g. be "Scanning...".

Issues in examples

Arduino LED on/off TCP

Alert saying Failed to send the command… Shows up several times when you don't have an Arduino connected.

Arduino LED on/off BLE

Could be good with an Alert if an Arduino is not connected

Arduino Scriptable

Alert saying Failed to send the command… Shows up several times when you don't have an Arduino connected. Get stuck in a loop where Alerts keep coming up.

BLE Discovery

When a device is found and you click to get more info, there is no way to get back to the main menu

BLE Sensor tag

Could be good with an Alert if a SensorTag is not connected.

It is a bit hard to know what the different colored graphs represents and how they are changed when you move a magnet or the phone.
Could we consider to have accelerometer as the default example where the colored graphs represent the 3 axis of movement?

iOS: Avoid 300 ms onclick event delay by e.g. using fastclick.js library.

In iOS there is a 300 ms delay between clicking e.g. a button and that its onclick event gets fired. Avoid this by for example using the fastclick.js library. Try first to solve the problem in a simpler way that doesn't require inclusion of any libraries.