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