A. First Steps with OpenDevice

In this tutorial we will show the steps to use OpenDevice and easily communicate with the devices.
The features will be displayed progressively, from a simple USB connection to a webserver using REST and WebSocket.

Hardware

In this first tutorial we will use the Arduino to be the most popular platform.

For this sample you need only a PC and Arduino (or compatible like one of EnergiaIDE).

Software

Java SDK
Eclipse
Arduino IDE

Because the Arduino be a device with very little processing power and storage, it is often necessary to use a computer to store the data in a database or to make processing and analysis of these data as well as integrate with other applications.

This first example is pretty basic'll just focus on communication.

Step 1 - Installing the library in Arduino

To install the library, you can simply clone the repository: opendevice-lib-arduino and put OpenDevice in /libraries folder of Arduino.

git clone https://github.com/OpenDevice/opendevice-lib-arduino OpenDevice

You can also install through the Library Manager, find OpenDevice in category: Communication

Please note that the library also requires some other libraries to function properly, when used with other connection types or sensors, like the library UIPEthernet for the Enc28j60 chip.

You can find all the links inside the README file of the library.

For a more detailed guide: http://www.arduino.cc/en/guide/libraries

Step 2 - Upload example in to Arduino

When you import the library, a menu for OpenDevice will be created in 'examples' menu. Choose UsbConnection example, plug arduino and click in upload !

You can control more IO pins using: OpenDevice::addDevice(12, Device::DIGITAL); // The next ID will be the 2

Step 3 - Create a new Java project with maven

If you already work with maven can skip this part, catching only the pom.xml example.

The best way to start with Java and Maven is using an IDE like Eclipse or Netbeans, we use Eclipse to be the most practical and does not require installation, simply download and unzip.

3.1 Create a project

1. Click on menu: File > New > Maven Project
If not in the NEW menu, choose Other and browse the list

2. Choose simple project in next step:

3. Set the name and the group

4. Create um new Java Class

3.2 Add OpenDevice dependency

OpenDevice libraries are managed by maven, he is responsible to download and set up, you simply configure the pom.xml

pom.xml

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<groupId>com.example</groupId>
	<artifactId>opendevice-tutorial</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<properties>
		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
		<opendevice-version>0.1.2-SNAPSHOT</opendevice-version>
	</properties>
	<dependencies>
		<dependency>
			<groupId>br.com.criativasoft.opendevice</groupId>
			<artifactId>opendevice-connection-stream</artifactId>
			<version>${opendevice-version}</version>
		</dependency>
		<dependency>
			<groupId>br.com.criativasoft.opendevice</groupId>
			<artifactId>opendevice-core</artifactId>
			<version>${opendevice-version}</version>
		</dependency>
	</dependencies>
	
    <repositories>
        <repository>
            <id>oss.sonatype.org</id>
            <url>https://oss.sonatype.org/content/repositories/releases</url>
        </repository>
        <repository>
            <id>oss.sonatype.org-snapshot</id>
            <url>https://oss.sonatype.org/content/repositories/snapshots</url>
        </repository>
    </repositories>
</project>

3.3 Running Demo.java

Demo.java source

import br.com.criativasoft.opendevice.core.SimpleDeviceManager;
import br.com.criativasoft.opendevice.core.connection.Connections;
import br.com.criativasoft.opendevice.core.model.Device;
import br.com.criativasoft.opendevice.core.model.DeviceType;

public class Demo extends SimpleDeviceManager {
    public static void main(String[] args) throws Exception {
        new Demo();
    }
    public Demo() throws Exception {
        Device led = new Device(1, DeviceType.DIGITAL);
        // setup connection with arduino/hardware
        addOutput(Connections.out.usb()); // Connect to first USB port available

        connect();
        addDevice(led);
        while(true){
            led.on();
            delay(200);
            led.off();
            delay(200);
        }
    }
}

Now you must see the LED blinking in the Arduino

Of course you can use the "SimpleDeviceManager" without using inheritance only calling instance.

Other usage style, it's working directly with the connection.
It is more decoupled, but less powerful

BlinkCommandDemo

import br.com.criativasoft.opendevice.connection.ConnectionListener;
import br.com.criativasoft.opendevice.connection.ConnectionStatus;
import br.com.criativasoft.opendevice.connection.DeviceConnection;
import br.com.criativasoft.opendevice.connection.message.Message;
import br.com.criativasoft.opendevice.core.command.DeviceCommand;
import br.com.criativasoft.opendevice.core.connection.Connections;

public class BlinkCommandDemo implements ConnectionListener {
    public BlinkCommandDemo() throws Exception {
        DeviceConnection conn = Connections.out.usb();
        conn.addListener(this);
        conn.connect();
        long delay = 500;
        while(conn.isConnected()) {
            conn.send(DeviceCommand.ON(1)); // '1' is Device ID not pin !
            Thread.sleep(delay);
            conn.send(DeviceCommand.OFF(1));
            Thread.sleep(delay);
        }
        System.out.println("TERMINATED !");
    }
    
    public static void main(String[] args) throws Exception {
        new BlinkCommandDemo();
    }

    // ------------------------------------------------------------
    // ------------- ConnectionListener Impl --------------------------
    public void onMessageReceived(Message message, DeviceConnection connection) {
        String type = message.getClass().getSimpleName();
        System.out.println("onMessageReceived("+type+"): "+ message);
    }
    public void connectionStateChanged(DeviceConnection connection, ConnectionStatus status) {
        System.out.println("connectionStateChanged :  " + status);
    }
}

Now that you have control of the gates of Arduino, you can control various devices such as lamps, fans, coffeemakers, robots, etc. ..

To control this type of device you will need a relay, which is a device capable of controlling high voltages.

Examples:

These modules are ready, but it's quite easy to build your own, if you have some knowledge in electronics.

Reference: http://openenergymonitor.org/emon/buildingblocks/mains-ac-relay-module
Tutorial: http://www.instructables.com/id/Connecting-a-12V-Relay-to-Arduino/

The examples and code used in this tutorial can be found here:
https://github.com/OpenDevice/OpenDevice/tree/master/examples/opendevice-tutorial

See next step: Adding REST Support

Troubleshooting

If you have a problem, check this guide: Troubleshooting