EK-5209-5 Evaluation Kit i-Bean® 916 MHz Wireless Sensor Network User’s Guide Document Number: Revision: Released: DOC-0005 01 July 2004
COPYRIGHT This manual is produced and copyrighted by Millennial Net, Inc. Any use or reproduction of the contents of this manual without the prior written consent of Millennial Net, Inc. is strictly prohibited. NOTICE All title and copyrights to this document are owned by Millennial Net, Inc. No part of the contents of this document may be reproduced or transmitted in any form or by any means without the written permission of Millennial Net, Inc. Millennial Net, Inc.
CAUTION All device installation, configuration, and reconfiguration must be performed only by qualified service personnel. Initialization of the product should be performed only by a qualified systems administrator. Compliance Statement FCC compliance for Millennial Net’s EK-5209-5 Evaluation Kit (916MHz, 5-3-1) consisting of the following models/components: • iB-5209 Endpoint • GW-5209 Gateway • RT-5209 Router Compliance Statement (Part 15.
vi EK-5209-5 Evaluation Kit User’s Guide
Table of Contents About This Guide Audience ....................................................................................................................xiv How to Use This Guide ...............................................................................................xiv Symbols and Conventions ........................................................................................... xv Contacting Millennial Net ..................................................................................
Configure Persistence Attributes ...............................................................................3-22 Configure Serial and ADC Data Formats ...................................................................3-23 Select Com Port on Host PC......................................................................................3-24 View Monitor Statistics .............................................................................................3-25 View Contents of Event Log File...............
List of Figures Figure 1-1. Figure 1-2. Figure 2-1. Figure 2-2. Figure 2-3. Figure 2-4. Figure 2-5. Figure 2-6. Figure 3-1. Figure 3-2. Figure 3-3. Figure 3-4. Figure 3-5. Figure 3-6. Figure 3-7. Figure 3-8. Figure 3-9. Figure 3-10. Figure 3-11. Figure 3-12. Figure 3-13. Figure 3-14. Figure 3-15. Figure 3-16. Figure 3-17. Figure 3-18. Figure A-1. Figure A-2. Figure B-1. Figure B-2. Figure B-3. Figure B-4. Figure B-5. Figure B-6. i-Bean network ..............................................................
x EK-5209-5 Evaluation Kit User’s Guide
List of Tables Table 2-1. Table 2-2. Table 3-1. Table 3-2. Table 3-3. Table A-1. i-Bean Gateway Status LEDs .......................................................................... 2-5 i-Bean Router Status LEDs.............................................................................. 2-8 Edit Device window functions........................................................................ 3-7 Watch window functions ..............................................................................
xii EK-5209-5 Evaluation Kit User’s Guide
About This Guide This section provides information related to the content of the user guide: • ’Audience’ on page -xiv • ’How to Use This Guide’ on page -xiv • ’Symbols and Conventions’ on page -xv • ’Contacting Millennial Net’ on page -xvi EK-5209-5 Evaluation Kit User’s Guide xiii
Audience This guide is intended for the following qualified service personnel who are responsible for installing and operating the EK-5209-5 Evaluation Kit: • System installer • Hardware technician • System operator • System administrator How to Use This Guide The sections of this guide provide the following information: Section xiv Provides Chapter 1, “Introduction” Overview of i-Bean network.
Symbols and Conventions This guide uses the following symbols and conventions to emphasize certain information. Note: A note is used to highlight important information relating to the topic being discussed. Caution A caution means that a specific action could cause harm to the equipment or to the data. Warning A warning describes an action that could result in physical injury, or destruction of property. Hazard A hazard is a particular form of warning related expressly to electric shock.
Contacting Millennial Net World Wide Web Millennial Net maintains a site on the World Wide Web where information on the company and its products can be found. The URL is: www.millennialnet.com Customer Support For answers to your technical questions, Millennial Net’s Customer Service department can be reached at: phone: 781.222.1030 e-mail: support@millennialnet.com Technical Publications Millennial Net is committed to providing you with quality technical documentation.
1 Introduction This chapter provides an overview of the i-Bean network and evaluation kit.
Introduction Product Overview Millennial Net's EK-5209-5 Evaluation Kit contains everything you need to set up a self-organizing, wireless star-mesh network. Once installed, you are able to observe the performance and operation of the network components and prototype your application. The EK-5209-5 Evaluation Kit contains one i-Bean Gateway, three i-Bean Routers, and five i-Bean Endpoints.
i-Bean Network Overview i-Bean Network Overview Millennial Net's innovative, self-organizing network technology combines micro-power sensor interface i-Bean Endpoints and i-Bean Routers with an i-Bean Gateway to form a reliable, scalable star-mesh wireless network (see Figure 1-1). This is a unique solution for low data-rate networks that provides both long battery life at the sensor interfaces and fault-tolerant networking.
Introduction i-Bean Gateways interface the i-Bean network to your host PC. They aggregate data from the network and act as a portal to monitor performance and configure network parameters. i-Bean Gateways connect via an RS-232 connection to the host PC, which in turn could be connected to a LAN or the Internet through one or more physical-layer interfaces, including RS-232, Ethernet, 802.11, landline or cellular modem.
Evaluation Kit Contents Evaluation Kit Contents The EK-5209-5 Evaluation Kit contains the following: • (5) iB-5209 Endpoints. • (3) RT-5209 Routers. • (1) GW-5209 Gateway. • Terminal board with battery for each i-Bean Endpoint, which is factory installed on a terminal board. • Antennas for each i-Bean Router and i-Bean Gateway. • Battery holder and (2) AA batteries for each i-Bean Router and i-Bean Gateway (battery holder for the i-Bean Gateway is factory installed inside its enclosure).
Introduction 1-6 EK-5209-5 Evaluation Kit User’s Guide
2 Kit Installation This chapter provides the following i-Bean network installation information: • ’Installing the i-Bean Wireless Network’ on page 2-2 • ’Hardware Installation’ on page 2-3 • ’iB-5209 Network Monitor Installation’ on page 2-10 EK-5209-5 Evaluation Kit User’s Guide 2-1
Kit Installation Installing the i-Bean Wireless Network This section of the user’s guide describes how to install the evaluation kit’s hardware and software components, which are installed in the following order: 1. i-Bean Gateway (see ’i-Bean Gateway Setup (GW-5209)’ on page 2-3) 2. i-Bean Routers (see ’i-Bean Router Setup (RT-5209)’ on page 2-6) 3. i-Bean Endpoints (see ’i-Bean Endpoint Setup (iB-5209)’ on page 2-9) 4.
Hardware Installation Hardware Installation The following procedures describe in order, how to install the various hardware components of the evaluation kit. When initially setting up the hardware, it is recommended that the i-Bean Gateway, i-Bean Routers, and i-Bean Endpoints be placed close to the host PC. This will make verifying proper network installation and operation easier when first establishing a session with iB-5209 Network Monitor. The devices can then be moved away from the host PC as needed.
Kit Installation 2. Connect the RS-232 cable between the i-Bean Gateway and the host PC. 3. (recommended power connection) Plug the factory-installed AC adapter into a 110 VAC power source. The i-Bean Gateway’s internal power switch is set to ON, so LED 2 (green) illuminates as soon as power is applied (see Table 2-1 on page 5 for LED operation). 4. (optional power connection) This step is only required when using the internal battery pack to supply power the device.
Hardware Installation i-Bean Gateway status LED operation Table 2-1 describes how the status LEDs on the i-Bean Gateway behave. Table 2-1. i-Bean Gateway Status LEDs Device Status • LED1 (red) LED2 (green) Power off Off Off • Power on N/A • Host PC connected Illuminates; flashing (0.5 second On/ 0.
Kit Installation i-Bean Router Setup (RT-5209) The i-Bean Routers, model number RT-5209, are shipped without cases to provide full access to the various I/O connectors. (While the i-Bean Gateway has similar connectors, they are only functional on the i-Bean Router.) Refer to Figure 2-3 on page 2-7 for locations of the various i-Bean Router switches and connectors described in the following procedure. Caution A jumper is factory-installed on JP1 that connects pins 2 and 3 together.
Hardware Installation Figure 2-3. i-Bean Router components (SL1) Power Connector Battery or AC Adapter Pin 1(right): GND Pin 2(left): + Antenna Power Jack (N/A) LED 1 (red) Signal Indicator REV-SMA Antenna Connector LED 2 (green) Power Indicator (SL2) N/A (JP1) Jumper Pins 2 & 3 jumped (SL4) ADC A/D Converter Connector RS-232 Port (SL3) DIO Digital I/O Connector Power Switch ON/OFF RS-485 Connector (SL6) N/A (SL7) N/A (SL8) N/A (SL5) UART Connector Notes: 1.
Kit Installation i-Bean Router status LED operation Table 2-1 describes how the status LEDs on the i-Bean Router behave. Table 2-2.
Hardware Installation i-Bean Endpoint Setup (iB-5209) The i-Bean Endpoints, model number iB-5209, are mounted to terminal boards as shown in Figure 2-4. A terminal board provides easy access to I/O connections and the power switch. The terminal board also contains a battery holder and battery for supplying power to the i-Bean Endpoint. The label on top of the i-Bean Endpoint denotes the last three digits of the device ID assigned to the i-Bean Endpoint. Figure 2-4.
Kit Installation iB-5209 Network Monitor Installation The procedures in this section describe how to do the following: 1. 2. Use the CD-ROM shipped with the evaluation kit to install the following Millennial Net items on the host PC: – iB-5209 Network Monitor – API examples – API documentation – iB-5209 i-Bean Endpoint Data Sheet – GW-5209 i-Bean Gateway and RT-5209 i-Bean Router Data Sheet – EK-5209-5 Evaluation Kit User’s Guide Open an iB-5209 Network Monitor session.
iB-5209 Network Monitor Installation Figure 2-5.
Kit Installation Launching iB-5209 Network Monitor To launch iB-5209 Network Monitor and verify proper communication with the i-Bean network nodes (see Figure 2-6): 1. Do one of the following to launch iB-5209 Network Monitor: 2. – Double-click on the desktop’s iB-5209 Network Monitor icon. – From the Windows’ taskbar, select: Start>All Programs>iB-5209>iB-5209 Network Monitor. Verify that all network nodes are discovered and displayed by iB-5209 Network Monitor. Figure 2-6.
3 iB-5209 Network Monitor Operations This chapter provides the following iB-5209 Network Monitor information: • ’iB-5209 Network Monitor Overview’ on page 3-2 • ’Setting Thread Priority’ on page 3-6 • ’Configuring a Node’s Operation’ on page 3-7 • ’Creating an Event Log File’ on page 3-21 • ’Configure Persistence Attributes’ on page 3-22 • ’Configure Serial and ADC Data Formats’ on page 3-23 • ’Select Com Port on Host PC’ on page 3-24 • ’View Monitor Statistics’ on page 3-25 • ’View Content
iB-5209 Network Monitor Operations iB-5209 Network Monitor Overview Millennial Net’s iB-5209 Network Monitor is a monitoring and management system for iB-5209 networks. This management tool will discover and display active i-Bean Routers in the vicinity of the i-Bean Gateway, and i-Bean Endpoints in the range of the i-Bean Gateway and i-Bean Routers as shown in Figure 3-1.
iB-5209 Network Monitor Overview As shown in Figure 3-1, the main window is divided into the following sections: Menu Bar From the menu bar, system users access the following: • Monitor This menu option provides access to the following functions: • – Thread Priority: This setting refers to the priority level of the iB-5209 Network Monitor program in a MS Windows operating system environment. For details, see ’Setting Thread Priority’ on page 3-6.
iB-5209 Network Monitor Operations Gateway This section displays the following information on the i-Bean Gateway connected to the host PC’s RS-232 port: • Com Port: Host PC’s RS-232 port connected to i-Bean Gateway. • ID: Device identifier assigned to the i-Bean Gateway. The ID consists of two octets (A.B), where each octet’s value = 000 to 255. • Group: Group identifier assigned to the i-Bean Gateway.
iB-5209 Network Monitor Overview • Interval: Time of the last message generated by a node. This value is synchronized with the sampling interval of the node. Time is displayed in either seconds (s) or minutes (m). • RX Packets: Number of packets successfully delivered to iB-5209 Network Monitor from a node since the node was detected by the i-Bean Gateway. The counter is reset if one of the following actions occur: – The node is powered down. – The i-Bean Gateway is powered down.
iB-5209 Network Monitor Operations Setting Thread Priority When iB-5209 Network Monitor is installed on a host PC using a MS Windows operation system, the priority level the program can be adjusted. The setting of Thread Priority affects how the iB-5209 Network Monitor program is handled by the Windows operating system, which in turn affects the reliability of data communications among the i-Bean network nodes as well as between the i-Bean Gateway and the host PC.
Configuring a Node’s Operation Configuring a Node’s Operation From iB-5209 Network Monitor’s menu bar, selecting Edit>Devices displays the Edit Device window used to configure the operation of an i-Bean Endpoint or i-Bean Router. Figure 3-2 shows a sample of the Edit Device window. Figure 3-2. iB-5209 Network Monitor’s Edit Device window Table 3-1 describes the functions of the various sections of the window as shown in Figure 3-2. Table 3-1.
iB-5209 Network Monitor Operations Table 3-1. Edit Device window functions (continued) Item F Description AD Converter Function This panel is used to control the states of the AD (Analog-to-Digital) Converter channels. For details, see ’Configuring AD (analog-to-digital) Converter Operation’ on page 3-17. G Serial Interfaces This panel is used to select a serial I/O operation for a device: Digital UART, RS-232 (RT-5209 only), or RS-485 (RT-5209 only).
Configuring a Node’s Operation Using Watch function to display current I/O information To display the current status information relating to the node’s interfaces (see Figure 3-3): 1. Select Edit>Devices. The Edit Device window opens. 2. Using the Select Device panel, enter the device ID of the desired node, then select Set. The node’s device ID displays in the Current ID panel. 3. Select Watch. The Watch window opens, displaying the selected node’s I/O status information. Figure 3-3.
iB-5209 Network Monitor Operations Table 3-2. Watch window functions (continued) Item C D E 3-10 Description DIO Channels Sampling Interval Serial Data Function This panel displays the following information for each digital channel (0–3): • State: Current input/output state of the channel • Desired: Desired input/output state of channel, which can be changed using the Edit>Devices option. • Value: I/O values of the channel (1 or 0). • Desired: Desired I/O value of channel.
Configuring a Node’s Operation Configuring Sample Interval of Single Node To configure the time interval between data packets transmitted by a node (see Figure 3-4): 1. Select Edit>Devices. The Edit Device window displays. 2. From the Select Device panel, enter the device ID of the desired node and click Set. The Edit Device window is now ready to make any changes to the selected node. 3. Using the Sampling Interval panel, enter the interval as a multiple of 100 milliseconds.
iB-5209 Network Monitor Operations Figure 3-5. Configuring sample interval of all nodes 1 Select Edit>All Sampling Intervals 2 Configure interval time 3 Select All Configuring Digital I/O Operation The following procedure describes the steps that need to be taken to set up the hardware and configure an i-Bean Endpoint or i-Bean Router for digital I/O operation (see Figure 3-6). Note: (i-Bean Endpoints only) There are factory-installed jumpers on the digital I/O terminal connectors (D0–D3, VCC).
Configuring a Node’s Operation Digital Output Setup 1. Connect the digital signal destination devices to the connectors (D0–D3) and ground (GND) of the following: – i-Bean Endpoint’s digital terminal block (located on terminal board). – i-Bean Router’s terminal pins (connector SL3). See Figure 3-6 on page 3-14 for connector locations. 2. From iB-5209 Network Monitor, select Edit>Devices. The Edit Device window displays. 3. Enter the device ID of the desired node and click Set.
iB-5209 Network Monitor Operations Figure 3-6.
Configuring a Node’s Operation Configuring UART Operation The following procedures describes how to use the i-Bean Endpoint’s digital I/O connections or the i-Bean Router’s UART connector for serial/UART communications (see Figure 3-7). Refer to the technical specification sheets for the i-Bean Endpoint and i-Bean Router for additional information required when using the device for serial communications. Note: 1.
iB-5209 Network Monitor Operations Figure 3-7.
Configuring a Node’s Operation Configuring AD (analog-to-digital) Converter Operation The following procedure describes the steps that need to be taken to set up the hardware and configure an i-Bean Endpoint or i-Bean Router for AD Converter operation (see Figure 3-8): 1. Connect 0–3 VDC signals to the following A/D Converter connectors: – i-Bean Endpoint: Connect signal source ground to GND_CPU of the A/D Converter terminal block.
iB-5209 Network Monitor Operations Configuring RS-232 Operation (RT-5209 only) The following procedure describes the steps that need to be taken to set up the hardware and configure an i-Bean Router for RS-232 operation (see Figure 3-9): 1. Use a DB-9 cable to connect the network device to the RS-232 female connector using the pinout information provided in Figure 3-9. 2. From iB-5209 Network Monitor, select Edit>Devices. The Edit Device window displays. 3.
Configuring a Node’s Operation Configuring RS-485 Operation (RT-5209 only) The RS-485 interface of the i-Bean Router operates using the following parameters: • Half-duplex mode • 9600 baud • Transmitting data: Maximum byte length for one request is 80 bytes • Receiving data: Reception is terminated by the router when the maximum input byte length is reached or there is no input for more than 20 ms. Once the input is terminated, the data is transferred to iB-5209 Network Monitor.
iB-5209 Network Monitor Operations Labeling i-Bean Endpoint or i-Bean Router The following procedure describes the steps required to assign a label to an i-Bean Endpoint or i-Bean Router (see Figure 3-11): 1. From iB-5209 Network Monitor, select Edit>Labels. The Edit Labels window displays. 2. Enter the Device ID of the desired i-Bean Endpoint or i-Bean Router. 3. Enter the label to be applied to the node(s), then select Set.
Creating an Event Log File Creating an Event Log File The following procedure describes the steps required to have iB-5209 Network Monitor record reported network events to a log file (see Figure 3-12): 1. From iB-5209 Network Monitor, select Edit>Logging. The Edit Logging window displays. 2. Configure the following i-Bean Router and i-Bean Endpoint log file attributes: 3. – Log up/down events: Record times when a node goes offline/online.
iB-5209 Network Monitor Operations Configure Persistence Attributes The following procedure describes how to configure the persistence setting of the network’s i-Bean Endpoints and i-Bean Routers (see Figure 3-13): 1. From iB-5209 Network Monitor, select Edit>Pesistence. The Edit Persistence window displays. 2. Configure the following persistence attributes: 3. – Enable device persistency: If selected, all nodes will be monitored and displayed even if they go offline.
Configure Serial and ADC Data Formats Configure Serial and ADC Data Formats The following procedure describes how to configure the format of displayed serial and ADC information (see Figure 3-14): 1. From iB-5209 Network Monitor, select Edit>Data format. The Edit Data Format window displays. 2. Configure the following network attributes: 3. – Serial data format: Select the desired format for displaying serial data (ASCII/Hex/Decimal).
iB-5209 Network Monitor Operations Select Com Port on Host PC The following procedure describes how to select the RS-232 com port for iB-5209 Network Monitor to use to communicate with the i-Bean Gateway (see Figure 3-15): 1. From iB-5209 Network Monitor, select Edit>Com Port. The Edit COM Port window displays. 2. Select the RS-232 com port to use from the drop down list of available ports, then select OK. iB-5209 Network Monitor will communicate with the i-Bean Gateway connected to the selected port.
View Monitor Statistics View Monitor Statistics The following procedure describes how to view the network statistics recorded by iB-5209 Network Monitor, which provides information on the packets received and transmitted by the network nodes (see Figure 3-16): 1. 2. From iB-5209 Network Monitor, select View>Monitor Statistics. The Monitor Statistics window opens, displaying the following information: – Started Time: Date/time statistics recording session began. – Current Time: Current date and time.
iB-5209 Network Monitor Operations View Contents of Event Log File The following procedure describes how to view the network event log file generated by iB-5209 Network Monitor, which records node-generated events (see Figure 3-17): 1. From iB-5209 Network Monitor, select View>Log. The log file window displays the user-defined event log information (see also ’Creating an Event Log File’ on page 3-21). 2.
View Contents of Event Log File Table 3-3. Event Log Key Definitions (continued) Key Key Meaning SubKey Sub-Key Meaning Output to device example Input to device example EP Endpoint N/A N/A EP=001.001 EP=001.002 FH First Hop Router N/A N/A N/A FH=001.002 HC Hop COunt N/A N/A N/A HC=3 LH Last Hop Router N/A N/A N/A LH=002.003 RCV Receive N/A N/A N/A RCV=200 (sequence number) RT Router N/A N/A RT=200.001 RT=200.
iB-5209 Network Monitor Operations Enable Multiple Capture Multiple capture is a special feature that enables iB-5209 Network Monitor to report the surrounding router information of a given device (an i-Bean Endpoint or a i-Bean Router that has endpoint functionality). When the Multiple Capture function of a device is enabled, all i-Bean Routers within direct communication distance to that device will report their existence to iB-5209 Network Monitor.
A API Functions This chapter describes the following API functions: • ’iB-5209 API Overview’ on page A-2 • ’i-Bean API Functions Overview’ on page A-4 • ’iBeanAPI.h’ on page A-5 • ’iBeanAPI_IO.h’ on page A-16 • ’iBeanAPI_Utils.
iB-5209 API Overview The iBeanAPI sub-directory contains five sub-directories which hold the API related files, including header files, dll and library files, and various compiled examples along with their source code listings. Figure A-1 is a representation of the directory structure. Figure A-1. iBeanAPI directories The contents of each directory is described below. bin Directory: This sub-directory contains iMDLL5k.dll file required for running API related applications.
iB-5209 API Overview Src Directory: This sub-directory contains the source code and their corresponding Microsoft Visual Studio .Net solution files. When these examples are build from these solution files the executables are generated in the bin directory.
i-Bean API Functions Overview Table A-1 provides a list of API functions (version 2.0) associated with i-Bean network products. Table A-1. i-Bean API functions iBeanAPI.
iBeanAPI.h iBeanAPI.h Data Structures 1. ibApi_APIHANDLE typedef ibApi_UINT16 ibApi_APIHANDLE; This handle represents an API session. It is created by ibApi_Open() and used by most of the other API functions. 2. ibApi_RESULT typedef enum ibApi_RESULT_e ibApi_RESULT; The API functions are standardized to return the value ibApi_RESULT, which is a signed 32-bit integer. If the integer is negative, then it is an error code such as ibApi_RESULT_ERR_INVALIDHANDLE or ibApi_RESULT_ERR_NOTPERMITTED.
5. ibApi_COMPARISON enum ibApi_COMPARISON_e { ibApi_COMPARISON_LESSTHAN, ibApi_COMPARISON_EQUAL, ibApi_COMPARISON_GREATERTHAN }; typedef enum ibApi_COMPARISON_e ibApi_COMPARISON; This enum is used for the return value of functions that compare things. Note that these values are non-negative to enable casting as ibApi_RESULT. 6.
iBeanAPI.h This data structure is used by ibApi_GetDeviceInfo() to report static device attributes that are fixed at manufacturing time. Structure Fields: struct_size The value sizeof (ibApi_DEVICEINFO) should be assigned to this field prior to calling ibApi_GetDeviceInfo(). This allows future versions of the API to extend the struct without breaking binary compatibility. device_type The type of the device (endpoint, router, etc.).
This struct is used by ibApi_FUNC ibApi_GetDeviceStatus() to report read-only device properties that change with time. Structure Fields: struct_size The value size of (ibApi_DEVICESTATUS) should be assigned to this field prior to calling ibApi_GetDeviceStatus(). This allows future versions of the API to extend the struct without breaking binary compatibility. hop_count The hop count measures a device's topological distance from the gateway. If the device talking directly to the gateway (i.e.
iBeanAPI.h The ibApi_VERSION type is used by functions such as ibApi_GetApiVersion() to encode version numbers as a 32-bit integer. Binary compatibility is only guaranteed when the major and minor components are the same. Note that this is a non-negative number to enable casting as ibApi_RESULT. 13. ibApi_EXPECTED_VERSION #define ibApi_EXPECTED_VERSION ibApi_MAKE_VERSION(1,0,0) This macro encodes the API version number that the application was compiled with.
Functions 1. ibApi_Open ibApi_FUNC ibApi_Open( ibApi_VERSION ibApi_CONST ibApi_CHAR * ibApi_CONST ibApi_CHAR * ); expected_version, server_type, connection_str ibApi_Open() should be called to initialize the API before any other function is called. The “server_type” parameter specifies the type of connection, and connection_str contains various connection parameters that vary according to server type. Notes: 1.
iBeanAPI.h This function returns the actual software version for the API, which can differ from ibApi_EXPECTED_VERSION if DLL’s are mixed. Return Value: An IbApi_VERSION value if successful, error code (<0) if not. 4. ibApi_GetNetworkList() ibApi_FUNC ibApi_GetNetworkList( ibApi_APIHANDLE ibApi_GROUPID ibApi_UINT32 api_hdl, networks[], networks_size ); This retrieves a list of group ID’s for the networks managed by the server.
This retrieves the ID’s of the devices in the network. The device_type parameter is a bitwise OR of the ibApi_DEVICETYPE constants that filters the result. (To retrieve all devices, use ibApi_DEVICETYPE_ANY.) Parameters: param api_hdl: (input) API handle returned from ibApi_Open(). network: (input) Group ID of the network. device_type: (input) Device type filter. devices: (output) Array of device ID’s to store the result. devices_size: (input) Maximum size for devices[].
iBeanAPI.h This function retrieves various read-only device properties whose values can change with time. See ibApi_DEVICE STATUS above for details. Note: To avoid memory corruption, size of (ibApi_DECVICESTATUS) must be assigned to the “struct_size” field prior to calling this function. Parameters: api_hdl: (input) API handle returned from ibApi_Open(). device_id: (input) ID of device to be accessed. device_status: (output) Pointer to variable storing the result.
This function sets the sampling interval for the device. The sampling interval determines how frequently updates occur; lower values mean quicker response times, at the price of higher bandwidth and power consumption. Typically the current interval must elapse before the new interval will be programmed. When the update has completed, the device state will return from ibApi_DEVISESTATE_REFRESHING to ibApi_DEVICESTATE_ONLINE.
iBeanAPI.h This function implements the simplest form of event notification using the application thread content: It causes the calling thread to sleep until a network packet has arrived (i.e., the sequence number has incremented), and then returns the ID of the device that was updated. If multiple devices have changed since the last call, ibApi_WaitForDeviceEvent() will return their ID’s in sequential round-robin order.
iBeanAPI_IO.h Data Structures 1. ibApi_IO_SERIALMODE enum ibApi_IO_SERIALMODE_e { ibApi_IO_SERIALMODE_DISABLED, ibApi_IO_SERIALMODE_RS232 }; typedef enum ibApi_IO_SERIALMODE_e ibApi_IO_SERIALMODE; This is used by ibApi_IO_SERIALCONFIG to select the serial interface. 2. ibApi_IO_SERIALCONFIG struct ibApi_IO_SERIALCONFIG_s { ibApi_UINT32 struct_size; ibApi_IO_SERIALMODE mode; }; typedef struct ibApi_IO_SERIALCONFIG_s ibApi_IO_SERIALCONFIG; Structure Fields: 3.
iBeanAPI_IO.h This structure is used by ibApi_IO_GetDeviceCaps() to return various static device attributes that are predetermined at manufacturing time. Structure Fields: struct_size The value size of (ibApi_IO_DEVICECAPS) should be assigned to this field prior to calling ibApi_IO_GetDeviceCaps(). This allows future versions of the API to extend the struct without breaking binary compatibility. num_dio_channels This is the number of DIO channels (i.e.
2. ibApi_IO_SetADCConfig() ibApi_FUNC ibApi_IO_SetADCConfig ( ibApi_APIHANDLE ibApi_DEVICEID ibApi_UINT8 ibApi_BOOL ); api_hdl, device_id, channel_index, enabled This sets whether the specified ADC channel is enabled or disabled. The channel must be enabled before calling ibApi_IO_ReadADC(). Parameters: api_hdl: (input) API handle returned from ibApi_Open(). device_id: (input) ID of the device to be accessed. channel_index: (input) Channel index to access.
iBeanAPI_IO.h This retrieves the value of the specified ADC channel, measured in volts. Note that this is computed by normalizing the raw reading relative to the battery voltage, and this calculation influences the precision of the result. Parameters: api_hdl: (input) API handle returned from ibApi_Open(). device_id: (input) ID of the device to be accessed. channel_index: (input) Channel index to access. adc_value: (output) Result of the ADC reading in volts.
This queries whether the specified DIO channel is configured for input or output. Parameters: api_hdl: (input) API handle returned from ibApi_Open(). device_id: (input) ID of the device to be accessed. channel_index: (input) Channel index to access. Return Value: An ibApi_IOMODE value if successful, or an error code (<0) if not. 7.
iBeanAPI_IO.h This reads the value of the specified DIO channel. If the channel is configured for output, it reads the current output value. Note: In some product models, the DIO pins are shared with the serial data interface and will be disabled when it is active. Parameters: api_hdl: (input) API handle returned from ibApi_Open(). device_id: (input) ID of the device to be accessed. channel_index: (input) Channel index to access. Return Value: Digital 0 or 1, or an error code (<0). 9.
11. ibApi_IO_GetSerialBufferStatus() ibApi_FUNC ibApi_IO_GetSerialBufferStatus ( ibApi_APIHANDLE ibApi_DEVICEID ibApi_IOMODE ); api_hdl, device_id, io_mode For the given device, this function retrieves the status of the out going serial data buffer. The return value gives the number of empty packet slots in the buffer. A negative return value denotes an error and a zero return value means there is currently no out going empty packet slots.
iBeanAPI_IO.h 13. ibApi_IO_ReadSerial() ibApi_FUNC ibApi_IO_ReadSerial ( ibApi_APIHANDLE ibApi_DEVICEID ibApi_UINT8 ibApi_UINT8 ibApi_UINT8 ); api_hdl, device_id, buffer[], buffer_size, seq_num For the given device, this retrieves the user data packet that arrived most recently. The ibApi_IO_SERIALMODE setting must have been previously something other than ibApi_IO_SERIALMODE_DISABLED. The input buffer holds a single packet (i.e., an arriving packet overwrites the previous one).
iBeanAPI_Utils.h Functions 1. ibApi_Utils_GetErrorDescription() ibApi_FUNC ibApi_Utils_GetErrorDescription( ibApi_RESULT ibApi_CHAR * ibApi_UINT32 ); error_code, description, description_size This function returns an English language interpretation for an API error code. Parameters: error_code: (input) ibApi_RESULT to be interpreted. description: (output) Pointer to buffer storing the text. description_size: (input) Maximum size of buffer.
iBeanAPI_Utils.h 3. ibApi_Utils_ConvertTextToGroupID() ibApi_FUNC ibApi_Utils_ConvertTextToGroupID( ibApi_CONST ibApi_CHAR * ibApi_GROUPID * ); group_id_text, group_id This parses a text string such as “1.2.3.4” and stores the result in the group_id structure. If fewer than 4 digit groups are provided, the result is left-padded with 0’s. Parameters: group_id_text: (input) Buffer to be parsed. group_id: (output) Structure to store the result.
This parses a text string such as “1.2.3.4.5.6.7.8” and stores the result in the device_id structure. If fewer than 8 digit groups are provided, the result is left-padded with 0’s. Parameters: group_id_text: (input) Buffer to be parsed. group_id: (output) Structure to store the result. Return Value: ibApi_RESULT_SUCCESS if successful, error code (<0) if not.
Example API Code Example API Code Millennial Net provides as part of the evaluation kit, several example API applications. This section examines in detail one of the API examples, ListDevicesVC7, including the code it uses. ListDevicesVC7 provides a list of all detected network nodes (i-Bean Gateway, i-Bean Router(s), and i-Bean Endpoint(s)).
ListDevicesVC7 Code The C file containing the code shown here can be found in the Programs directory: Programs\iB-5209\iBeanAPI\Src\ListDevices /* * ListDevices.c * * Copyright (c) 2000-2004 Millennial Net, Inc. All Rights Reserved. * Reproduction or modification is strictly prohibited without express * written consent of Millennial Net. * * This example illustrates the basic operations of connecting to the i-Bean * API and obtaining basic information about the devices in the network.
Example API Code /***************************************************************************/ void WaitForKey(void) { printf("\r\nPress any key to close..."); _getch(); printf("\r\n"); } /**************************************************************************** * This is a simple wrapper for detecting and reporting API error return * values. In C++, this function could throw an exception object.
/***************************************************************************/ void ListDevices(ibApi_APIHANDLE api_hdl) { #define DEVICEIDS_MAX 100 ibApi_GROUPID groupid; ibApi_DEVICEID deviceids[DEVICEIDS_MAX]; int deviceids_count; char deviceid_text[256]; int sampling_interval; int i; ibApi_DEVICEINFO deviceinfo; ibApi_DEVICESTATUS devicestatus; /* * The ibApi_GetNetworkList() function returns a list of the groups * currently managed by the network.
Example API Code CheckResult(ibApi_GetDeviceInfo(api_hdl,deviceids[i],&deviceinfo)); CheckResult(ibApi_Utils_ConvertDeviceIdToText(deviceids[i], deviceid_text,sizeof(deviceid_text),MIN_DEVICEID_WORDS)); printf(" %10s fw=\"%s\" hw=\"%s\"\r\n", deviceid_text, deviceinfo.firmware_version,deviceinfo.hardware_version); } /* * List the routers. */ printf("\r\nROUTERS\r\n"); deviceids_count = CheckResult(ibApi_GetDeviceList(api_hdl, groupid, ibApi_DEVICETYPE_ROUTER|ibApi_DEVICETYPE_ROUTERBEAN, deviceids,DEVICE
CheckResult(ibApi_Utils_ConvertDeviceIdToText(deviceids[i], deviceid_text,sizeof(deviceid_text),MIN_DEVICEID_WORDS)); sampling_interval = CheckResult(ibApi_GetSamplingInterval(api_hdl,deviceids[i])); printf(" %10s (%i ms)\r\n", deviceid_text, sampling_interval); } } /***************************************************************************/ int main() { /* * This handle represents the current API session.
B Sample Application This chapter contains information on how to perform the sample application included with the EK-5209-5 Evaluation Kit: • ’Application Overview’ on page B-2 • ’Application Setup & Operation’ on page B-4 • ’Changing Temperature Sensor Battery’ on page B-7 EK-5209-5 Evaluation Kit User’s Guide B-1
Application Overview Millennial Net includes a sample application in the EK-5209-5 Evaluation Kit. This application demonstrates a real-world application of the Millennial Net's endpoint peripheral interface and how it is used for monitoring and data collection purposes across a wireless network. The EK-5209-5 Evaluation Kit includes a temperature sensor assembly with a 10,000 Ohm Kele sensor (Type 3) that changes resistance as its environmental temperature changes.
Application Overview Figure B-2 describes the process flow. Figure B-2.
Application Setup & Operation The following procedures describe how to set up the iB-5209 hardware and software for creating the evaluation kit’s sample application. Note: Before this sample application can be executed, you must install the iB-5209 Evaluation Kit’s hardware and software according to the instructions found in Chapter 2, “Kit Installation”. The i-Bean Gateway must be installed and powered on, and iB-5209 Network Monitor must be running before proceeding.
Application Setup & Operation Launching TempMonitor Application To launch the TempMonitor application (see Figure B-4): 1. From the Windows task bar, select Star>All Programs>iB-5209>API Examples. The Examples window opens with a list of options. 2. Select TempMonitor from the Examples window. TempMonitor launches. Figure B-4.
TempMonitor Overview The TempMonitor application displays temperature changes vs. time for one device only. Use the Device Selection area to select the endpoint with matching device ID, then click Update button to configure the device (enable ADC channel 1). The Run/Stop button is used to control the display curve updating; Run means continuously update the curve, Stop means to freeze the current curve. The precise reading can also be obtains from the Realtime Sensor Reading(F) area. Figure B-5.
Changing Temperature Sensor Battery Changing Temperature Sensor Battery The temperature sensor assembly comes with a factory installed lithium battery. The procedure below describes how to replace the battery when needed. Millennial Net recommends using the following replacement battery type: DigiKey Part Number: P189-ND (phone: 1-800-DIGI-KEY). To replace the battery (see Figure B-6): 1. Use an Allen wrench to turn in the two set screws holding the cover to the base and remove the cover. 2.
B-8 EK-5209-5 Evaluation Kit User’s Guide
Index A AD Converter configuring 3-17 API overview B-2 C com port select 3-24 configuring ADC 3-17 digital I/O 3-12 RS-232 3-18 RS-485 3-19 sample interval 3-11 UART operation 3-15 D data format configure (serial and ADC) 3-23 Digital I/O configuring 3-12 digital input setup 3-12 digital output setup 3-13 E Edit Device window 3-7 ESD warning 1-5 evaluation kit contents 1-5 overview 1-2 event log file create 3-21 view 3-26, 3-28 F frequency band 1-2 H hardware installation 2-3 host PC requirements 1-5
Index overview B-6 Thread Priority 3-6 transmission distances 1-2 U UART configuring 3-15 W Watch function 3-9 window 3-9 Index-2 EK-5209-5 Evaluation Kit User’s Guide
