From openPicus Wiki
Jump to: navigation, search


What is DooIP


DooIP (Do Over IP) is an open protocol to allow easy interaction of smartphones and tablets with OpenPicus Flyport devices. The protocol uses JSON strings and UDP broadcast messages to discover and control Flyport without the need of programming the devices. All of the hardware APIs of the OpenPicus framework are exposed and can be controlled using the JSON commands. A discovery service is embedded in the protocol, so any device can send at any time a discover message to poll the devices on the network. In the same way, any device connecting to the network sends an announce message, containing information about its network address and hardware. In this way, at anytime, every device knows exactly how the local DooIP Network is composed and what are the operating devices.

The concept

Today, an Android Developers who wants to communicate with the real world, is provided only with a development environment, the so-called Android Open Accessory Development Kit, released directly by Google several months ago. It is based on USB connection and it leverages the compatibility with the beloved Arduino boards, allowing you to develop Android accessories such as docking stations, usb speakers, etc...

Anyone, who has actually used it, knows that Android OADK has some limitations. OADK is based on USB communication between Android and an external device and its commands are strongly based on the USB protocol. Using OADK a physical cable (USB) connection is required in order to communicate between the endpoints and it is basically possible to connect only one device at a time.

The overall picture makes the OADK a not properly fitting solution when it comes to domotics for example: imagining your "home" as an Android accessory is probably hard.

The question was: how to create a system that will allow you to connect as many devices as you want with your Android terminal also helping you to do it remotely and wirelessly?

Our Choice

Once again we have chosen standardization, simplicity and performance. That means using using UDP as a transport protocol and JSON as a communication protocol. For those not familiar with it, JSON is a specific lighweight client-server communication protocol that is lighter and easier to manage - in comparison with XML for example - that is really widespread these days.

Thanks to the fruitful cooperation with our friends from AreaMobile, we have encapsulated the generation of commands that are needed to control the FlyPort via DooIP remotely in an Android java library that is easily adoptable by the developer (great jobe mates!).

The protocol

Every message of the protocol is sent through UDP broadcast on port 50000 and is presented as JSON string. At the moment there are two different messages in the DooIP protocol:

  • command messages: are the commands sent to control one Flyport or all the Flyport connected to the network. In the future will also be possible to control groups of Flyport.
  • status messages: are the messages sent by Flyport as answer to some specific request, as acknowledge to commands or as notification for specific events (like power on).

Command messages

The command messages are used to control the devices on the network, and contain the following fields:

  • sender: the MAC address of the sender of the message;
  • receiver: the receiver for the message. In case the message is addressed to all the devices this field will be FF:FF:FF:FF:FF:FF;
  • timestamp: UTC time expressed in millis;
  • password: (for future use), a password to grant different user access;
  • group: (for future use) the receiver can also be a group of devices. In case it’s different from 0, the command is a “group command”, otherwise it’s a single or total command and the MAC address of the receiver is specifies the destination;
  • opcode: specifies the command to execute with a particular opcode, as shown in the following table;
  • acknowledge: specifies if the command requires an acknowledge from the executing device.
  • argv[ ]: array containing the arguments for the command.

Follows an example of a command message:

	"exec": {
		"sdr": "aa:bb:cc:dd:ee:ff",
		"rcv": "00:11:22:33:44:55",
		"time": "1234567890",
		"pwd": "xxx",
		"grp": 0,
		"op": 3,
		"ack": false,
		"argv": [
		    {"type": 1, "val": 5}

The number of parameters of the “argv” field can vary according to the type of opcode. In the following table are reported the supported opcode and the parameters needed:

Opcode Command Description Answer
0 Network scan Scan request from. Any device on the network must answer announcing it’s features JSON string with the parameters of the device...
1 IOPut(int pin, int value) Set, clears or toggles a specific pin of Flyport module -
2 IOInit (int pin, int value) Initializes a specific pin with a function specified by value. -
3 IOGet (int pin) Reads the status of the specified pin. Value of the requested pin
4 IOButtonState (int pin) Performs a check on a “press” or “release” event on a specific pin used as pushbutton. Value of the pressure
5 ADCInit() Initializes the ADC module -
6 ADCVal(int channel) Reads the value from the specific analog channel The value of the channel
7 UARTInit(int port, long int baud) Initializes the specific port with the value baud -
8 UARTOn(int port) Activates the specific UART port -
9 UARTOff(int port) Turns off the specific UART port -
10 UARTFlush(int port) Flushes the buffer of the specified UART port -
11 UARTBufferSize (int port) Reads the number of characters in the RX buffer of the specified port The number of chars in the RX Buffer
12 UARTRead(in tport, int n') Reads n characters from the specified UART port The number of characters successfully read
13 UARTWriteCh (int port, char ch) Writes the character ch on the specified UART port -
15 PWMInit (BYTE pwm, float freq, float duty) Initializes the specified PWM module pwm with the desired frequency freq and duty cycle duty -
16 PWMOn (BYTE n, BYTE pwm) Activates the desired pwm on the pin n -
17 PWMDuty (float duty, BYTE pwm) Sets the duty cycle duty of the desired pwm -
18 PWMOff (BYTE pwm) Turns off the specified pwm -

Flyport module will return an answer only in the cases specified in the table. In the other cases, to get an acknowledge of the command, the field “ack” of the JSON string must be set to true.

The types of the parameters are coded according to the following rules:

Type Code
int 1
float 2
double 3
char 4
long int 5
string 6

Taking a look at the last two tables it’s possible to decode the previously presented sample message. The opcode 3 means the command IOGet, while the parameter type 1 means int and the value 5 is the number of the pin. The previous JSON message is a command to read the state of the pin number 5 for the device with the MAC address 00:11:22:33:44:55, sent by the device with MAC address aa:bb:cc:dd:ee:ff.

Status messages

The status messages can be sent by a device following a specific request, or due to a Flyport Module internal event. The fields sent with a status message are:

  • device (dev): MAC address of the device who sent the message (in this case the Flyport);
  • receiver (rec): MAC address of the device of the receiver who should be interested (should be a specific device or a broadcast message);
  • type: the number representing the type of the status message. Following is a table of possible values:
Value Type of message Description
0 Event report It is sent when a particular event is fulfilled, for example at device startup
1 Command reply It is sent as a reply of a specific command, like a pin status request
2 Acnowledge It informs that the message was received well by the device

NOTE: In the release 0.1 it is provided only type 1, and for type 0 only the announce message;

  • timestamp: it is the timestamp of message that caused the reply;
  • subtype: its meaning changes with the value of the type parameter. Following is a table of possible values:
Type Subtype functionality
0 Report of what type of event caused the status message
1 Opcode of the message that caused this message
2 Not used yet

NOTE: In the release 0.1 it is provided only type 1, and for type 0 only the announce message;

Also in this case it is shown an example of status message:

		"sdr": "aa:bb:cc:dd:ee:ff",
		"rcv": "aa:bb:cc:dd:ee:ff",
		"time": "UTC in millis",
		"type": 1, // type of the status message
		"subt": 1, // message subtype
		"argv": [
		    {type: type of the parameter,val: value of the parameter},
		    {type: type of the parameter,val: value of the parameter},]

argv[] is the array container of values returned by the execution of the requested command
the returned parameters could be more (like the Network Scan command).
In case of no parameters requested, the argv array will be void.

Network setup

The mobile device (Android or others) must be in the same network of the Flyport modules.

  • Every mobile device executes a network scan. Every Flyport modules replies to this scan with informations about MAC address, Netbios name, Flyport Model(Flyport Wifi or Flyport Ethernet), the program ID (for future development);
  • Every new Flyport module that joins the network send an “announce” message with its own MAC address and Netbios name (and eventually the event of the status message...);

At this point, the mobile devices know every device connected to the network simply querying the network scan.
Flyport announce message example:

		"sdr": "MAC address of FLYPORT",
		"rcv": "ff:ff:ff:ff:ff:ff",
		"time": "0000000000000",
		"type": 0,
		"subt": 0,
		"argv": [
		    {"type": "6","val": "NetbiosName"},
		    {"type": "6","val": "MACaddrFlyport"},
		    {"type": "6","val": "FlyportModel"},
		    {"type": "1","val": id}

The “FlyportModel” parameter stores the type of FLYPORT module used:

  • ‘W’: The Module used is a FLYPORT Wi-Fi
  • ‘E’: The module used is a FLYPORT Ethernet

Announce messages are sent when a Flyport power on and joins a network.

NOTE: In the release 0.1 it is provided only the network scan by mobile devices libraries. All the announce messages of Flyport Modules will be ignored by the mobile devices.

Download DooIP firmware for Flyport

The DooIP basic firmware for Flyport Wi-Fi and Flyport Ethernet modules is yet in work in progress. The current release is 0.3 and its purpose is for beta testers.

You can download it here (google code)

Install DOoIP on Flyport

The files released are "hex" file. This mean that them are ready to be downloaded on Flyport modules without need to use openPicus IDE. OpenPicus core team developed a stand-alone downloader called firmware downloader based on ds30 Loader. This software is a almost stable release and works on Windows environment. For further problems, please post a topic on openPicus forum.

Firmware Dowloader Tool

The usage of firmware downloader is simple:

  • Launch the file called Firmware downloader.exe;
  • Select the COM port where programmer is attached. Both USBNest and miniUSB programmer are compatible with the tool;
  • Open the desired .hex file:
    • please select the Wifi version if you are flashing firmware on a Flyport Wi-Fi module, or the Ethernet version for Flyport Ethernet module;
  • Click on Download and wait for the end of the procedure;

How to use the firmware

Once the new firmware is downloaded, your Flyport module starts with the DooIP application. Like many just provided application notes, the first action Flyport executes is to connect to the Network. Flyport Ethernet and Flyport Wi-Fi performs different actions when them try to connect to a network:

  • Flyport Ethernet is set to access to network using DHCP Client, so if you connect it to a router/access point using a RJ45 cable it will give a random IP address from the DHC Server. This IP Address will be printed on UART1.
  • Flyport Wi-Fi is set to create/connect to an adhoc network with SSID "dooipwifi". In this way, using your PC you can connect to this wireless network and customize Flyport network parameters from the configuration page. For further references, please take a look at the related application note

To start testing DooIP firmware, please refer to AreaMobile APIs for DooIP protocol on Android Platform, or get started with some preliminary demos:

To test DooIP using a PC, we suggest to start with TCP/IP Builder sending broadcast UDP packets like this network scanner JSON string:

{"exec": {"sdr": "PC_MAC_ADDRESS","rcv": "ff:ff:ff:ff:ff:ff","time": "1234567890","pwd": "xxx","grp": 0,"op": 3,"ack": false,"argv": [{"type": 1, "val": 5}]}}

where PC_MAC_ADDRESS is your PC network card MAC address value

and then take advance of all the other type of commands to send

Personal tools