Coalesenses iSense User manual

iSense Ethernet Gateway User Guide

2 / 30
iSense Ethernet Gateway User Guide
coalesenses
research to innovate
Document history
Version Date Changes
1.0 30.08.2011 Initial version
1.1 04.05.2012 Minor corrections

3 / 30
iSense Ethernet Gateway User Guide
coalesenses
research to innovate
Contents
1. General Description........................................................................................................................ 6
1.1. Handling and Security Instructions.......................................................................................... 7
2. Programming of the Ethernet Gateway .......................................................................................... 8
3. Net10Module API Description ....................................................................................................... 8
3.1. Extended Constructor............................................................................................................... 8
3.2. Standard Constructor ............................................................................................................... 9
3.3. set_led ...................................................................................................................................... 9
3.4. set_button_handler................................................................................................................. 10
3.5. ethernet................................................................................................................................... 10
3.6. sd_card ................................................................................................................................... 10
4. SDCard API Description .............................................................................................................. 11
4.1. Constructor............................................................................................................................. 11
4.2. is_ready.................................................................................................................................. 11
4.3. is_write_protected.................................................................................................................. 11
4.4. get_number_of_blocks........................................................................................................... 12
4.5. access ..................................................................................................................................... 12
4.6. access_block .......................................................................................................................... 12
4.7. read......................................................................................................................................... 13
4.8. read_block.............................................................................................................................. 13
4.9. write ....................................................................................................................................... 14
4.10. write_block ....................................................................................................................... 14
5. Enc28J60 API Description ........................................................................................................... 15
5.1. constructor.............................................................................................................................. 15
5.2. send ........................................................................................................................................ 16
5.3. enable ..................................................................................................................................... 16
5.4. enable ..................................................................................................................................... 16
5.5. set_receiver ............................................................................................................................ 16
5.6. address.................................................................................................................................... 17
5.7. max_packet_size .................................................................................................................... 17
6. Ethernet Gateway Module Demo Application.............................................................................. 17
6.1. Obtaining the Ethernet Gateway Module Demo Application ................................................ 17
6.2. Compiling the Ethernet Gateway Demo Application ............................................................ 18
6.2.1. Using Eclipse............................................................................................................... 18
6.2.2. Using the Command Line............................................................................................ 21

4 / 30
iSense Ethernet Gateway User Guide
coalesenses
research to innovate
6.3. Flashing the Ethernet Gateway Module Demo Application .................................................. 22
6.4. Ethernet Gateway Module Demo Application functionality.................................................. 22
7. References .................................................................................................................................... 29

5 / 30
iSense Ethernet Gateway User Guide
coalesenses
research to innovate
About this User Guide
In this user guide,
•files and folders are represented in the Arial typeface,
•code fragments, function names etc. are represented in the Courier New typeface,
•GUI elements such as button descriptions etc. are represented in “quotation marks”,
•titles of other documents are presented in Italic type.
This manual assumes that the reader has successfully installed the iSense development environment,
and obtained the iSense standard firmware. For further information on these steps, consult the
Development Environment Setup User Guide [1].
In addition, it is assumed that the user is familiar with the use of iShell. For further information on
iShell, consult the iShell User Guide [3].
For further information on iSense firmware programming concepts and on application development, it
is recommended to read the Writing iSense Applications User Guide [4].

6 / 30
iSense Ethernet Gateway User Guide
coalesenses
research to innovate
1. General Description
The iSense Ethernet Gateway is based on a Jennic JN5148 wireless microcontroller [5], a chip that
combines the controller and the wireless communication transceiver in a single housing.
The controller provides 32 bit RISC computation and runs at a software-scalable frequency between 4
and 32 MHz. It comprises 128kbytes of memory that are shared by program code and data. The
advantage of this choice is that memory consumption of program code and data can be traded.
Opposite to other controllers where the user is limited to a certain amount of data and code memory,
free choices that are only bounded by the sum of both become possible here.
The radio part complies with the IEEE 802.15.4 standard [6]. It achieves a data rate of 250 kBit/s,
provides hardware AES encryption and is ZigBee-ready. Besides IEEE 802.15.4 standard compliant
operation, the radio transceiver provides two additional modes of operation, offering increased data
rates of 500 kBit/s and 667 kBit/s. It reaches a receive sensitivity of -98dBm (at 250 kBit/s) and a
transmit power of up to 10 dBm.
Apart from that the Ethernet Gateway is equipped with an IEEE 802.3i complaint 10BaseT 10Mbit
full-duplex interface which allows to build a gateway between IEEE 802.15.4 wireless sensor
networks and Ethernet based LAN infrastructures. Another benefit is the microSD slot which to allows
to read and write data to a microSD card.
To enable long, but still synchronous sleep and wakeup cycles, the module is equipped with a high
precision clock (error < 3ppm). The Core Module also features software-switchable LEDs for
debugging purposes.
There is a 34 pin connector (X1) on both sides of the module where other modules can be attached to
the Core Module. It can supply up to 500mA to other modules.
The controller can be programmed in various ways. While over-the-air programming (OTAP) is
possible and considered to be the standard procedure, the program can also be transferred via the
gateway module, or using a special programming adapter that mates with corresponding pads on the
module.
While by default powered by a wall mount adapter directly connected to the gateway, it can also be
supplied with power over the Ethernet cable by using an optional power injector, enabled by setting
the jumpers J1/J2.
Figure 1: Mechanical Information

7 / 30
iSense Ethernet Gateway User Guide
coalesenses
research to innovate
X1 System connector for plugging an iSense Core Module or other iSense modules
ETH RJ45 Ethernet Connector
P Power Connector
SD microSD slot
B1 User Button
J1/J2 Power Injector Jumper
1.1.Handling and Security Instructions
Note that all iSense Modules are sensitive to electro-static discharge. Appropriate protection measures
have to be taken.
If not protected by an appropriate housing, all iSense components must be protected from humidity,
mechanical impact, and short circuiting by contact with conductive materials.
Note that all cable plugs and headers are designed to be extremely compact, and are not intended for
frequent plugging and unplugging. Never pull the cables to remove the plugs from the corresponding
modules, always pull the plug itself. If required, use an appropriate tool (or the pulling cord if
available). Even though all plugs/headers are coded, be sure to pay attention to the proper orientation.
Never apply force. Never use cables if their insulation is damaged.
Note that iSense modules are not intended for hot-plugging, (dis-)connecting modules from or to other
modules in operation can result in a reset of the device and other undesired effects.
All delivered components are intended for use in research application. For using these components
within other application domains, consult coalesenses prior to use.
Coalesenses products are not intended for use in life support systems, appliances or systems where
malfunction of these products can reasonably be expected to result in personal injury, death or severe
property or environmental damage. Coalesenses customers using or selling these products for use in
such applications do so at their own risk and agree to fully indemnify coalesenses for any damages
resulting from such use.
Do not connect components or devices to any iSense component that are not manufactured or
distributed by coalesenses without prior consultation of coalesenses. Note that doing so regardless of
consultation will void the warranty and the declaration of CE conformity. Coalesenses customers
connecting third party devices do so at their own risk and agree to fully indemnify coalesenses for any
damages or injury resulting from such use.
Note that the SMA connector is sensitive to mechanical stress. Be sure not to apply forces to the
connector or a connected antenna. Protect the module from shock and vibration.

8 / 30
iSense Ethernet Gateway User Guide
coalesenses
research to innovate
2. Programming of the Ethernet Gateway
The Ethernet Gateway can currently be programmed in two ways. When having an already
programmed Ethernet Gateway it is likely that you are able to program the device wirelessly using
OTAP (Over The Air Programming). How to convenient program devices this way see [2]. The
second method uses the iSense Gateway Module 2 directly connected to the Ethernet Gateway.
Therefor you have to open the housing and connect the devices.
Figure 2: Ethernet Gateway with attached Gateway Module
The Result should look similar to Figure 2. In this configuration you can program the device according
to [3].
3. Net10Module API Description
The Net10Module class in the isense namespace contains all software functionality for operating
the Core Module-specific features, including
•switching the LEDs,
•handling of button events,
The NET10Module class is defined in src/isense/modules/ethernet_module/net10_module.h in
the iSense directory.
The iSense firmware is structured into a large number of software modules that can be (de-)activated
separately. The below API description for each function specifies the required modules that must be
activated to use the functions, and names both the web compilation module name as well as the
according code define. An asterisk (*) indicates that the respective module is activated in the iSense
standard firmware.
Required Modules:
NET10 module* #define ISENSE_ENABLE_NET10_MODULE
3.1.Extended Constructor
Net10Module::Net10Module( Os& os, uint64 mac_address, uint16 rx_length,

9 / 30
iSense Ethernet Gateway User Guide
coalesenses
research to innovate
bool full_duplex );
Description:
Extended constructor of the Net10 module, which allows to set the MAC-Address of the Ethernet
interface, the length of the receive buffer and, and whether or not the interface should operate in full
duplex mode. Instances of SDCard and Enc28J60 are created as well, when activated in the systems
configuration file isense/config.h.
Parameters:
os Reference to the operating system class
mac_address Desired link-layer address of the interface. Only the lower
48bits will be considered.
rx_length Desired length of the receive buffer
full_duplex Sets the interface to full duplex when set to true
3.2.Standard Constructor
Net10Module::Net10Module( Os &os );
Description:
Initializes the Net10Module class. By default, the LEDs are switched off. Instances of SDCard and
Enc28J60 are created as well, when activated in the systems configuration file isense/config.h.
Parameters:
os Reference to the operating system class Os
3.3.set_led
void Net10Module::set_led( uint8 led, bool on );
Description:
Switches on the modules LEDs (regardless of prior state).
Parameters:
led Number of LED to use. Use 0 to switch on LED1 and 1 to switch on LED2.
on Turns the LED on when set to true, turns the LED off when set to false

10 / 30
iSense Ethernet Gateway User Guide
coalesenses
research to innovate
3.4.set_button_handler
bool Net10Module::set_button_handler( ButtonHandler* button_handler );
Description:
Sets the ButtonHandler that will be called when the button B1 is pressed or released. The
ButtonHandler class can be found in isense/button_handler.h
Parameters:
button_handler Instance of the class ButtonHandler that should be called when the
button is pressed or released.
Returns:
true if the ButtonHandler could be registered, false elsewise.
3.5.ethernet
Enc28J60* Net10Module::ethernet( );
Description:
Returns the instance of the Enc28J60 Ethernet module, that was instantiated together with the
Net10Module
Returns:
Pointer to the Enc28J60 instance of the Net10Module instantiated by the constructor
Required modules:
Ethernet Module #define ISENSE_ENABLE_ETHERNET_MODULE
3.6.sd_card
SDCard* Net10Module::sd_card( );
Description:
Returns the instance of the SDCard module that was instantiated together with the Net10Module
Returns:
Pointer to the SDCard instance that was instantiated by the constructor of the Net10Module
Required modules:
Ethernet Module #define ISENSE_ENABLE_ETHERNET_SD_CARD_MODULE

11 / 30
iSense Ethernet Gateway User Guide
coalesenses
research to innovate
4. SDCard API Description
The Ethernet Gateway comes with an integrated microSD slot, which allows to read/write data from/to
a microSD card.
The SDCard class in the isense namespace contains all software functionality for operating the
SD Card-specific features, including
•writing data to a microSD card and,
•reading data from a microSD card
The SDCard class is defined in src/isense/modules/ethernet_module/SD_card.h in the iSense
directory.
Required Modules:
SD Card Module* #define ISENSE_ENABLE_ETHERNET_MODULE_SD_CARD
SPI* #define ISENSE_ENABLE_SPI
GPIO* #define ISENSE_ENABLE_GPIO
4.1.Constructor
SDCard::SDCard( OS& os );
Description:
Standard constructor. NOTE: An instance of SDCard is created when instantiating the
NET10Module. That instance can be obtained using the sd_card method, see 3.6.
Parameters:
os Reference to the current instance of the iSense operating system
4.2.is_ready
bool SDCard::is_ready( );
Description:
Returns if a fully initialized SD Card is in the SD card slot
Returns:
true if a SD-Card is inserted in the SD-Card slot which can be operated, false elsewise
4.3.is_write_protected
bool SDCard::is_write_protected( );
Description:

12 / 30
iSense Ethernet Gateway User Guide
coalesenses
research to innovate
Returns whether or not the SD Card is write protected or not
Returns:
true if the SD-Card in the SD-Card slot is write protected, false elsewise
4.4.get_number_of_blocks
uint32 SDCard::get_number_of_blocks( );
Description:
Returns the number of blocks of the currently inserted SD-Card
Returns:
Number of blocks of the SD-Card
4.5.access
uint8 SDCard::access( uint64 address, uint32 length, uint8* buffer, bool
write );
Description:
Reads or writes data to the SD Card. The returned value is the status code. Its upper 3 bytes are don’t
care bits. A successful write operation is indicated with a value of 5, a successful read operation with
0.
Parameter:
address The address which shall be accessed
length Determines how many bytes should be accessed
buffer Pointer to a buffer to/from which blocks are copied from/to the SD Card
write If true, the access will be a writing operation, otherwise it is a reading
operation
Returns:
Status code indicating whether the desired operation was successful or not. The upper three bits are
don’t care bits, the lower 5 indicate the status. A Value of 5of the 5 lower bits indicate a successful
write operation, a value of 0successful reading.
4.6.access_block
uint8 SDCard::access_block( uint32 block, uint32 length, uint8* buffer,
bool write );
Description:
Reads or writes data to the SD Card

13 / 30
iSense Ethernet Gateway User Guide
coalesenses
research to innovate
Parameter:
block The block which shall be accessed
length Determines how many bytes should be accessed. The length must be a
multiple of 512
buffer Pointer to a buffer to/from which blocks are copied from/to the SD card
write If true, the access will be a writing operation, otherwise it is a reading
operation
Returns:
Status code indicating whether the desired block-operation was successful or not. The upper three bits
are don’t care bits, the lower 5 indicate the status. A Value of 5of the 5 lower bits indicate a
successful write operation, a value of 0successful reading.
4.7.read
uint8 SDCard::read( uint64 address, uint32 length, uint8* buffer );
Description:
Reads a given number of bytes from a certain address of the SD Card. The method behaves exactly
like access, since it only calls access with the parameter write set to false.
Parameter:
address Start address to read from
length Determines how many bytes should be read
buffer Pointer to a buffer to which blocks are copied from the SD Card
Returns:
Status code indicating whether the desired read-operation was successful or not. The upper three bits
are don’t care bits, the lower 5 indicate the status. A value of 0indicates success.
4.8.read_block
uint8 SDCard::read_block( uint32 block, uint32 length, uint8* buffer );
Description:
Reads a given number of blocks starting at a certain block from the SD card. The method behaves
exactly like access, since it only calls access with the parameter write set to false.
Parameter:
block The block which shall be accessed

14 / 30
iSense Ethernet Gateway User Guide
coalesenses
research to innovate
length Determines how many bytes should be accessed. The length must be a
multiple of 512
buffer Pointer to a buffer to/from which blocks are copied from/to the SD Card
Returns:
Status code indicating whether the desired read-operation was successful or not. The upper three bits
are don’t care bits, the lower 5 indicate the status. A value of 0indicates success.
4.9.write
uint8 SDCard::write( uint64 address, uint32 length, uint8* buffer );
Description:
Writes a given number of bytes to a certain address of the SD card. The method behaves exactly like
access, since it only calls access with the parameter write set to true.
Parameter:
address The address to which shall be written
length Determines how many bytes should be read.
buffer Pointer to a buffer to which blocks are copied from the SD Card
Returns:
Status code indicating whether the desired write-operation was successful or not. The upper three bits
are don’t care bits, the lower 5 indicate the status. A value of 5indicates success.
4.10. write_block
uint8 SDCard::write( uint32 block, uint32 length, uint8* buffer );
Description:
Writes a given number of blocks starting at a certain block to the SD Card. The method behaves
exactly like access, since it only calls access with the parameter write set to true.
Parameter:
block The block to which shall be written
length Determines how many bytes should be written. The length should be a
multiple of 512
buffer Pointer to a buffer to which blocks are copied from the SD Card
Returns:

15 / 30
iSense Ethernet Gateway User Guide
coalesenses
research to innovate
Status code indicating whether the desired block-operation was successful or not. The upper three bits
are don’t care bits, the lower 5 indicate the status. A value of 5indicates success.
5. Enc28J60 API Description
The Ethernet Gateway comes with an Enc28J60 Ethernet chip, allowing the device to send and receive
packets using existing LAN infrastructure.
The Enc28J60 class in the isense namespace contains all software functionality for operating the
SDCard-specific features, including
•sending packets via Ethernet,
•receiving packets via Ethernet
The ENC28J60 class is defined in src/isense/modules/ethernet_module/enc28j60.h in the
iSense directory.
Beneath the low-level send and receive functionality as described in this document, there also exist a
high level API which enables the Ethernet Gateway to communicate with other network devices using
IPv4 / IPv6 as network layer protocol and TCP / UDP for transport. For further information on how to
use IP-based communication with the Ethernet Gateway please refer to [7].
Required modules:
Enc28J60 Module* #define ISENSE_ENABLE_ETHERNET_MODULE
SPI* #define ISENSE_ENABLE_SPI
GPIO* #define ISENSE_ENABLE_GPIO
5.1.constructor
Enc28J60::Enc28J60( Os& os, uint64 mac_address, uint16 rx_buffer_size,
bool full_duplex );
Description:
Constructor of the Ethernet Module
Parameter:
os Reference to the current Os
mac_address Desired 48-bits MAC-Address for this interface
rx_buffer_size Desired size of the receive buffer (6000 is a good choice)
full_duplex If true the full duplex mode will be turned on, half duplex when false

16 / 30
iSense Ethernet Gateway User Guide
coalesenses
research to innovate
5.2.send
void Enc28J60::send( const uint64 dest_addr, uint16 len, const uint8 buf,
uint8 options, Sender* sender );
Description:
Sends data using the Ethernet controller. The passed data will automatically embedded in an Ethernet
frame and sent to the interface with dest_addr.
Parameters:
dest_addr Destination address of the data
len Length of data to send
buf Pointer to the data to send
options Not considered
sender Not considered
5.3.enable
void Enc28J60::enable( );
Description:
Switches on the Ethernet controller
5.4.enable
void Enc28J60::disable( );
Description:
Switches off the Ethernet controller
5.5.set_receiver
bool Enc28J60::set_receiver( Receiver* receiver );
Description:
Sets an instance of class Receiver, that will be called upon reception of Ethernet packets.
Parameters:
receiver
Instance of class Receiver which should get passed received packets

17 / 30
iSense Ethernet Gateway User Guide
coalesenses
research to innovate
Returns:
true if the receiver was registered successful, false elsewise
5.6.address
uint64 Enc28J60::address( );
Description:
Returns the current MAC address of that interface
Returns:
Current MAC-Address of the Ethernet interface. REMEMBER: Only the lower 48bits must be
considered for determining the address, the upper 16bits are usually set to zero.
5.7.max_packet_size
uint32 Enc28J60::max_packet_size( );
Description:
Returns the maximum size of a packet that can be sent over that interface at once
Returns:
Maximum Transmission Unit (MTU) of the link. For Ethernet this value is 1500bytes.
6. Ethernet Gateway Module Demo Application
The Ethernet Gateway Module demo application exemplifies how an application can make use of the
Net10Module and SDCard API. It shows how to
•switch on and off the LEDs,
•set the ButtonHandler to handle events raised by pressing the button B1,
•as well as read and write data to an microSD card
Required modules:
Net10 module
#define ISENSE_ENABLE_NET10_MODULE
VSNPRINTF 2
#define ISENSE_ENABLE_VSNPRINTF_2
SD Card module
#define ISENSE_ENABLE_ETHERNET_MODULE_SD_CARD
6.1.Obtaining the Ethernet Gateway Module Demo Application
The NET10 Ethernet Gateway Demo Application can be obtained from [7].

iSense Ethernet Gateway
User
coalesenses
research to innovate
6.2.Compiling the
Ethernet Gateway
The next step is compiling the
Ethernet
6.2.1. Using Eclipse
If you want to use Eclipse for compiling
change to the “C++”
perspective.
You can now import the application into Eclipse. Choose “File”
open the “Import” dialog.
Choose “Existing projects into workspace”, and click on “Next”.
User
Guide
Ethernet Gateway
Demo Application
Ethernet
Gateway Module Demo Application.
If you want to use Eclipse for compiling
Ethernet Gateway
Demo Application, open Eclipse, and
perspective.
You can now import the application into Eclipse. Choose “File”

“Import” from the menu bar to
Choose “Existing projects into workspace”, and click on “Next”.
18 / 30
Demo Application, open Eclipse, and
“Import” from the menu bar to

iSense Ethernet Gateway
User
coalesenses
research to innovate
Click on
“Browse…”, and select the directory of the Core Module demo application, i.e.
NET10DemoApplication
in the
After doing so, the “NET10
DemoApplication
“Import” dialog.
User
Guide
“Browse…”, and select the directory of the Core Module demo application, i.e.
in the
iApps directory.
DemoApplication
”
project should appear in the projects list of the
19 / 30
“Browse…”, and select the directory of the Core Module demo application, i.e.
project should appear in the projects list of the

iSense Ethernet Gateway
User
coalesenses
research to innovate
If it doesn’t,
the typical reason is that there is already a project called “
Eclipse, i.e.
•you imported the
NET10
•
you created or imported a project with the same name before.
Be sure not to check “Copy projects into workspace” in the above dialog. Finish the import by clicking
on the “Finish” button.
As a result, you will find the “
NET10
User
Guide
the typical reason is that there is already a project called “
NET10
DemoApplicati
NET10
DemoApplication before or
you created or imported a project with the same name before.
Be sure not to check “Copy projects into workspace” in the above dialog. Finish the import by clicking
NET10
DemoApplication”
project in the “Project Explorer”
20 / 30
DemoApplicati
on” in
Be sure not to check “Copy projects into workspace” in the above dialog. Finish the import by clicking
project in the “Project Explorer”
.