Veseo

vNet
Network Virtualization Layer
for Arduino and Android

User Guide
VT-UxSI-01
 Copyright (C) 2011 Veseo

This program is free software: you can redistribute it and/or modify

it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,

but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.

Originally written by Dario Di Maio

Printed in Italy

Veseo
Napoli

Revision Control

Description Author Date Rev.

First draft Dario Di Maio 2011 Nov 24 A

II
Index
1 Purpose and Intended Audience .......................................................................................................4
1.1 Download Source Code.............................................................................................................4
1.2 Base Code..................................................................................................................................4
1.3 Credits........................................................................................................................................4
2 Overview ..........................................................................................................................................5
2.1 Peer to Peer Network.................................................................................................................5
2.2 Supported Network Architectures..............................................................................................5
2.2.1 Single Media......................................................................................................................6
2.2.2 Bridged Networks..............................................................................................................6
2.2.3 Routed Network.................................................................................................................6
2.2.4 Bridged and Routed Networks...........................................................................................7
3 Network Configuration Rules............................................................................................................8
3.1 Addressing Rules.......................................................................................................................8
3.2 Address Translation....................................................................................................................9
3.3 Routing and Bridging Rules......................................................................................................9
4 Application Methods........................................................................................................................11
4.1 vNet Drivers.............................................................................................................................12
4.1.1 Ethernet TCP/IP W5100...................................................................................................12
4.1.2 Chibiduino - 2.4 GHz IEEE 802.15.4..............................................................................13
4.1.3 Future drivers...................................................................................................................13
5 vNet Configuration..........................................................................................................................14
5.1 Drivers Configuration..............................................................................................................15
6 vNet for Android (in progress)........................................................................................................17
7 Souliss Project Distributed Home Automation.............................................................................18

III
Veseo
vNet User Guide
Doc. No.: VT-UxSI-01

1 Purpose and Intended Audience

This document help developers to proper set a vNet network, is intended for people
with a basic knowledge of electronics and telecommunication, focused on: wireless and
wired networks, IPv4 networks.

1.1 Download Source Code

Source code is available on SourceForge from VeseoTech account.

1.2 Base Code

The vNet layer code is based on:

Chibiduino Library by FreakLabs,

Ethernet Library by Arduino.

1.3 Credits

The vNet code is developed by Veseo and distributed as open source, you can use and

modify it as per General Public License GPL v3.

4/20
Veseo
vNet User Guide
Doc. No.: VT-UxSI-01

2 Overview
vNet is a network virtualization layer, that allow every application run over different
communication media without any change in the code. As additional feature, vNet
frames are routed and bridged automatically without any action on the application side,
creating a network of devices running over different communication medias, but
connected together.

vNet is developed for Arduino based platform, but the code can be easily ported over
different platforms. It support also Android based devices as node for the virtual
network.

2.1 Peer to Peer Network

vNet is intended as a software layer for P2P communication, so all the drivers for the
available communication media are forced as P2P. There is no concept of server/client,
master/slave or similar. Protocols behind vNet must have their own addressing and
filtering rules to identify owner and destination.

The applications on the top of vNet can use server/client, master/slave or similar
concept.

2.2 Supported Network Architectures

Basically vNet work all the architecture (out of ring, that is not fully supported) that
you can have with the supported media, the configuration may require different detail
based on the number of nodes and their interconnection.

5/20
Veseo
vNet User Guide
Doc. No.: VT-UxSI-01

Detail on supported communication media is given in next paragraph, in the below

example just consider M1 as communication media one (as instance, wired) and M2 as
communication media two (as instance, wireless).

2.2.1 Single Media

In this architecture all the nodes has the same communication media, could be either
M1 or M2.

Refer to example number 2 for an application of this architecture.

2.2.2 Bridged Networks

In this architecture there are three types of nodes: first type are nodes with M1
communication media, second type are nodes with M2 communication media, third
type are nodes with both M1 and M2.

In the simplest case, there are three nodes one for each type. Nodes first and second
type can exchange data via the third type, all nodes share the same application and the
vNet layer. One or more bridges are supported.

Refer to example number 3, 4 for an application of this architecture.

2.2.3 Routed Network

In this architecture there are two type of nodes, both share the same communication
media. Former type of nodes are standard, latter are SuperNode and are able to repeat a
message to cover longer distances. This solution is applicable for wireless networks.

SuperNodes can identify automatically the routed path to reach the destination node or
may require definition of routing tables in case of more complex networks.

6/20
Veseo
vNet User Guide
Doc. No.: VT-UxSI-01

Refer to example number 1 for an application of this architecture.

2.2.4 Bridged and Routed Networks

Is a case where the wireless networks use Nodes and SuperNodes, and one or more
bridge to the wired network.

Refer to example number 5 for an application of this architecture.

7/20
Veseo
vNet User Guide
Doc. No.: VT-UxSI-01

3 Network Configuration Rules

Bridging and routing facility are provided assuming the use of simple network
configuration rules, these allow a node to identify how bridge or route a message and if
these action are required.

3.1 Addressing Rules

The addressing rules used for vNet are mainly the same of IPv4 with one difference,
the length of the address. In vNet are used only two bytes (instead of 4 bytes as in
IPv4).

Furthermore, in vNet the addresses are split by media, this make easy identify which
media has to be used for the communication.

In the following table are shown the available ranges for all the media, the code support
up to five different media (not all are used up to now). A comparison of an address with
these ranges is used to find out the media of the relevant address.

Media First Address Last Address

M1 - Ethernet TCP/IP
0x0000 0x64FF
W5100
M2 - Chibiduino - 2.4 GHz
0x6500 0xAAFF
IEEE 802.15.4
M3 Not Used 0xAB00 0xBBFF
M4 Not Used 0xBC00 0xCCFF
M5 Not Used 0xCE00 0xFEFF

Each media has an associated subnet mask, using a bit-wise AND between address and
subnet mask, is obtained the subnet of the device.

8/20
Veseo
vNet User Guide
Doc. No.: VT-UxSI-01

3.2 Address Translation

vNet addresses use only two bytes, that should be translated in addresses usable for the
used media. As example, IPv4 protocol use four byte addresses and a translation from
two to four bytes is required. From a math point of view this translation cannot be
univalent, so some bytes should be forced using a base address. Basically the base
address is added to two bytes that came from the vNet address.

An address translation could create troubles, for example IPV4 routing will no longer
work, same for NAT. Is supported IP over the same subnet and VPNs.

Actually, only for IP based connection is required a translation because Chibiduino has
a two byte address.

3.3 Routing and Bridging Rules

Each communication interface has an its own subnet mask and is part of the relevant
subnet. As per IPv4 a bit-wise AND operation between the address and the subnet mask
give the subnet address.

Device within the same subnet must be in listening range, the concept of listening
range should be referred to the communication media that are used for the device. As
instance, for device that use wireless communication a listening range is the area where
the radio are able to send and receive message; for device that use a wired Ethernet a
listening range is the switched/routed IP network.

As per IPv4, frame that has a destination out of the own subnet are send to a device
with routing and/or bridging capability. In this case this device is called SuperNode
(and not Gateway) that will bridge or route the message.

A SuperNode address is typically the first available address for the subnet, so if you are

9/20
Veseo
vNet User Guide
Doc. No.: VT-UxSI-01

looking for the SuperNode of subnet subn you will send a message to subn &
0x0001. Additionally a routing table can be set to force preferred paths or not standard
addressing.

A device with two or more communication media is not automatically set as bridge, to
be a bridge require a SuperNode configuration. A SuperNode with two or mode
communication media, is able to bridge frames within its own media without any
additional configuration.

10/20
Veseo
vNet User Guide
Doc. No.: VT-UxSI-01

4 Application Methods
As described before, every application that use vNet can be used regardless the
communication media without any change in the code.

The following schematic shown the vNet structure, whatever is running on the
Application Layer can access one or more Media Interface through the vNet
Layer.

Application Layer

vNet Layer

Media Media Media Media Media

Int. Int. Int. Int. Int.
1 2 3 4 5

The vNet Layer is not able to auto identify the available hardware, so an additional
configuration is required to enable the available media and define node behavior.

The main functions that are used in the Application Layer are the followings:

U8 vNet_Send(U16 addr, U8 *data, U8 len, U8 port);

U8 vNet_DataAvailable();

U8 vNet_RetriveData(U8 *data);

The vNet_Send method send a message to a node identified with its address (addr), the
frame is automatically routed or bridged (if required).

11/20
Veseo
vNet User Guide
Doc. No.: VT-UxSI-01

The vNet_DataAvailable method looks for data available for any of the available
media, it will return the number of media that have at least one incoming message.

The vNet_RetriveData retrieve data from the buffer in order of media, should runs one
for each media that have at least one incoming message.

Other methods are available for setting up the address and routing/bridging rules for
complex architectures.

4.1 vNet Drivers

For each media interface supported is available a drivers, that is a collection of code
that care of communicatin protocol between the MCU and the relevant interface.

4.1.1 Ethernet TCP/IP W5100

This is basically the Ethernet library modified to fit the vNet requirements. Two are the
main modification:

There is no longer the concept of server and client as in standard TCP/IP, each
device has a P2P connection build over two sockets.

At every use of vNet_Send command, a connection is open and closed as soon

data are transferred. This allow multiple communication regardless the maximum
number of available sockets in W5100.

Each device has one socket always in listening mode and one socket ready to open a
connection. When data has to be sent, the device start a connection on the listening
socket of the target, send data e close the connection. The target device, receive data on
the listening socket, if an answer is required it open a connection to the listening socket
of the device that targeted it.

12/20
Veseo
vNet User Guide
Doc. No.: VT-UxSI-01

So, the listening socket became a RX channel rather the other the TX one.

4.1.2 Chibiduino - 2.4 GHz IEEE 802.15.4

This is the Chibiduino library from FreakLabs with few modifications:

The EEPROM usage is moved to the main code of vNet,

The methos are standarzided as per vNet.

vNet frame structure and parsing functionality are quite similar to Chibiduino, so its a
natural extentions of this code. The previous release of vNet was released as
Chibiduino with routing, that basically extend the listening range using middle node
(SuperNode) that acts as a repeater.

vNet is basically the same, but allow more than one communication media, so act also
as a bridge. The availability of more media make it a virtualization layer.

4.1.3 Future drivers

Next release of vNet will include RFM22B and WiFi libraries.

13/20
Veseo
vNet User Guide
Doc. No.: VT-UxSI-01

5 vNet Configuration
The vNet configuration is performed with the file vNet_Config.h where the used can
set the main options.

Following options are the most important:

//Vnet_Config.h
/**********************************************************/
/*!
If enabled allow broadcast support for incoming frames, to work properly
the same should be supported also by the communication media drivers.

Value SuperNode
0x0 Disable (Default)
0x1 Enable
*/
/**********************************************************/
#define VNET_BRDCAST 1

/**********************************************************/
/*!
A SuperNode is a device with routing and bridging capability, if Enable
message from Nodes of the own subnet can be sent out to other subnet.

SuperNode address should be the first usable address of the subnet.

Value SuperNode
0x0 Disable (Default)
0x1 Enable
*/
/**********************************************************/
#define VNET_SUPERNODE 0

/**********************************************************/

14/20
Veseo
vNet User Guide
Doc. No.: VT-UxSI-01

/*!
A Node or a Supernode can have one or more media interfaces active at
same time. A device (either Node or Supernode) automatically act as a
bridge between the active media.

Value Media
0x0 Disable (Default)
0x1 Enable

*/
/**********************************************************/
#define VNET_MEDIA1_ENABLE 0
#define VNET_MEDIA2_ENABLE 1
#define VNET_MEDIA3_ENABLE 0
#define VNET_MEDIA4_ENABLE 0
#define VNET_MEDIA5_ENABLE 0

The VNET_BRDCAST allow receiving broadcast message, send broadcast messages is

always possible also if the option is not set.

The VNET_SUPERNODE allow routing/bridging functionality for a device.

The VNET_MEDIAn_ENABLE enable the n-media. If more than one media is

activated, the VNET_SUPERNODE option is required to bridge the networks.

5.1 Drivers Configuration

Each driver has its own configuration file, in these are set the network parameters care
should be used to avoid misconfiguration. As instance, the MAC address for the
W5100 is set in the configuration file for the Ethernet drivers and not in the
application, device cannot share the MAC address; the Channel and PAN ID for
Chibiduino is set in the configuration file, devices that doesn't share these parameters
won't communicate.

15/20
Veseo
vNet User Guide
Doc. No.: VT-UxSI-01

Media Description Driver Configuration File

Number
1 Ethernet TCP/IP W5100 ethUsrCfg.h
2 Chibiduino - 2.4 GHz IEEE 802.15.4 chbUsrCfg.h
3 Not used -
4 Not used -
5 Not used -

16/20
Veseo
vNet User Guide
Doc. No.: VT-UxSI-01

6 vNet for Android (in progress)

The vNet libraries are developed also for Android operative system, these implement
only partially the vNet functionality because use only the Ethernet interface.

The Android developers has a class with the same methods available for Arduino, any
Android device can act as a vNet node. Frames from Android devices can reach every
node of the vNet regardless the network architecture.

Android based node doesn't support routing and bridging functionality.

17/20
Veseo
vNet User Guide
Doc. No.: VT-UxSI-01

7 Souliss Project Distributed Home Automation

vNet is part of a larger project called Souliss Home Automation its main goal is a
open source Distributed Home Automation Framework, based on Arduino and Android.

The main parts of Souliss for Arduino are the followings:

Souliss
Application

Home Hardware / Serial

Automation Definition

MaCaco Communication
Protocol

Memory Map

vNet Layer

Media Media Media Media Media

Int. Int. Int. Int. Int.
1 2 3 4 5

The Souliss Framework is composed by "Macaco Communication Protocol" and "vNet

Layer", and is a complete solution for Home Automation communication.

There is no master/slave or server/client concept, each node can read or write data from
other nodes, a node can be either an Arduino or Android based devices. Data can be

18/20
Veseo
vNet User Guide
Doc. No.: VT-UxSI-01

pulled or pushed from and to a device, subcriptions and polling modes are available.

The Souliss application can have different modules to fit the requirements, as base an
Home Automation module is provided, this will implement logics and exchange data
using the base framework; an optional module for ID and Automatic Addressing can be
used for small plug and play networks.

The Souliss for Android is a bit different, because is thinked to be a graphical interface
for the user and has one communication media (WiFi).

Souliss
Application

Home DHCP
Automation
Scheduler and Skins
Scenarios

Network Plugin
Definition Device
SQLite

MaCaco Communication
Protocol

vNet Layer

Media Int.
1

19/20
Veseo
vNet User Guide
Doc. No.: VT-UxSI-01

20/20