#
Getting Started - Digi Connect ME Integration Kit

## Overview

Getting started with the Digi Connect ME Integration Kit is as easy as:

1. Installing the software
2. Connecting and configuring the hardware
3. Running your existing application or a provided sample application.

Follow the steps and links in this Getting Started guide and you'll quickly become familiar with the Digi Connect ME product and its integration kit.

## Installing the Software

Since you're reading this document, you've probably already run the setup wizard for the integration kit. If not, you should do that now:

> Insert the CD. The CD should automatically launch the setup wizard, but if it doesn't, open the Windows Explorer and browse to the CD. Choose SetupME.exe to start the installer.

Some parts of the software setup are optional, and you may not have installed these components. You can run the setup wizard again if you decide to add any or all of these options. To install the optional software using the setup wizard, choose the `Advanced` install and pick the software to install from the components dialog. Optional software includes:

- Adobe Acrobat Reader
  Install Adobe Acrobat Reader if you don't have a viewer for PDF files. Many of the documents in the integration kit are supplied in PDF format. Version 5.1 of the Adobe Acrobat Reader installer is provided; other versions are available at the Adobe web site.
- Sun JRE (Java Runtime Environment)
  A Java plug-in for your Internet browser is required. The Digi Connect ME module uses a Java applet to display configuration and status information in a browser window. If your browser doesn't already have a Java plug-in installed, the applet will attempt to connect to the Sun web site and automatically find and install the correct plug-in. If you don't have an active Internet connection, or if you know you need the Java plug-in and want to install it manually, version 1.4.1-03 of the Sun JRE is provided. Newer versions may be found at the Sun web site.
- Internet Explorer 6
  Internet Explorer version 6 (with service pack 1) is provided for users who are running unsupported browsers. Supported browsers are Internet Explorer 5.5 and later, and Netscape Navigator 6 and later. Newer versions of Internet Explorer may be found at the Microsoft web site.
- Digi RealPort
  Digi RealPort adds COM ports to your computer that actually redirect communications to the remote Connect ME device. This is sometimes called COM port redirection. It allows the Digi Connect ME to appear and act the same as a physical COM port on your computer (e.g., COM1). If you use a terminal program or serial programming APIs to communicate with the device that you want to network enable, choose RealPort and no changes to your software are required. To install RealPort, follow the instructions for the version of Windows you are running.
  - RealPort installation for Windows 98 and Windows Me
  - RealPort installation for Windows NT4
  - RealPort installation for Windows 2000, Windows XP, and Windows Server 2003
- Sample Source Code
  Source code is provided that can be used as starting points for your own applications. Project files for the samples are provided for Microsoft Visual C++ version 6.

## Connecting and Configuring the Hardware

The hardware for the Digi Connect ME Integration Kit includes:

- a Digi Connect ME module
- a Development Board
- a power supply and set of power cords
- a pair of Ethernet cables, one straight-through and one cross-over
- a pair of DB-9 serial cables, one straight-through and one cross-over ("null-modem")
- a diagnostic loop-back plug
- a wrist strap

- CAUTION: Always wear a properly grounded wrist strap when handling the Digi Connect ME module or the development board. This helps prevent electrostatic discharge (ESD) and damage to the electronics.

Connect the hardware using the following steps:

1. Locate the socket for the ME module on the development board. Plug the module into the socket with the RJ-45 connector facing out from the development board. (Click here for a drawing of the development board and the location of the module socket).
2. Connect one of the Ethernet cables to the Digi Connect ME module. If you are connecting directly to a network card on your PC, use the cross-over Ethernet cable. If you are connecting to a hub or switch, use the straight-through Ethernet cable.
3. If you have equipment that you want to use with the Digi Connect ME module, and if it includes a serial communications port, connect it to serial port 1 (labeled `P2`) on the development board using one of the DB-9 serial cables.
4. Connect the power supply to the development board.
5. Visually confirm that the board is running and connected to the network. The power LED on the development board and the orange network link LED on the ME module should be lit.

Configure the device. The integration kit includes a device discovery program that locates Digi Connect ME modules on the network and allows you to set an IP address.

1. Click here and choose `Open` or `Run` to start the discovery program. You should see a Digi Connect ME device listed in the window. Verify that its MAC address matches the MAC address label provided with the Digi Connect ME module.
2. If an IP address is shown for the module, a DHCP server provided an IP address automatically. If you don't want to use DHCP, or if no IP address is shown, you will need to set a static IP address. If the module isn't already highlighted in the window, click on it to choose it. Choose `Configure Network Settings` in the `Device Tasks` window of the application. Enter the IP address, subnet mask, and optionally, the gateway, in the dialog that pops up. Save the settings.
3. If you changed the IP address of the device, wait a few seconds for it to restart, then refresh the view in the Digi Device Discovery application (choose `Refresh view` in the `Other Tasks` window). Confirm that the IP address shown is correct.
4. Choose `Open web interface` in the `Device Tasks` window. A web browser window will open and the configuration applet for the module will be displayed. If the browser does not have the correct Java plug-in enabled, there may be a delay before the main page is displayed. Installing the Java JRE (as described in the Installing Software section) will eliminate the initial delay of finding, downloading, and installing the plug-in as the page is loading.
5. The Digi Connect ME is now installed. You can browse the configuration applet running in the browser window, or continue to the Running Applications section of this guide.

## Running Applications & Communicating with the Connect ME

If you are network-enabling a device that communicates with a serial port on a PC, click here for information about configuring the Connect ME module to talk to your application.

If you are just getting started with the design of a network-connected product, the next step is to understand which of several communication models you should choose for the Connect ME module and the computer or other device talking to it.

### Selecting a Communications Model

- Digi RealPort®
  Digi RealPort is a COM port redirector or "serial-over-TCP/IP" communications model. Commands and data written to a standard serial port on a PC are intercepted, translated, and sent over the network to the Digi Connect ME module. Similarly, data sent from the Connect ME module over the network is translated so it appears to have been received by a standard serial port. Digi RealPort is completely transparent to the application running on the PC.

  Advantages: Works with any software that communicates with a standard serial port without modifying the application. Device drivers are available for all major operating systems. RealPort is an excellent choice if you have an existing device that is connected to a serial port.

  Disadvantages: Requires a customer to load the appropriate RealPort driver for the operating system on each computer that will communicate with the device.

- TCP (Transmission Control Protocol) Sockets
  TCP is a very reliable communications model. Because TCP is a connection-oriented protocol, one device will be configured as a client and the other will be configured as a server. Connect ME can operate as either a TCP Client or a TCP Server. The Client initiates communications, analogous to initiating a phone conversation by picking up the handset and dialing. The Server waits patiently for incoming connections and answers. TCP can also be run securely using SSL (Secure Sockets Layer). The rule of thumb for determining whether the Digi Connect ME should be configured as the TCP Client or as the TCP Server follows: If the Digi Connect ME is part of a device with a user interface and is typically the initiator of a data exchange, choose TCP Client; if the Digi Connect ME is part of a device that has no user interface and is typically listening for and responding to messages, choose TCP Server. Because the TCP Client usually initiates the conversation, some type of user interface on the TCP Client device is generally used to report errors in creating connections to the TCP Server. The TCP Server typically doesn't report connection failures since it can't know when the Client was unable to connect to it. An example of a Digi Connect ME solution configured as TCP Server would be a power meter connected to a power meter manager application. The application, acting as a TCP Client, initiates conversations with each power meter by sending a request to each one (the meters configured as TCP Servers) asking for the current readings. If the application is unable to connect to a Digi Connect ME module (TCP Server), it might report an error to the user and/or queue up another request for a later reading. An example of a Digi Connect ME solution configured as a TCP Client is a network-enabled airport baggage check-in that initiates a conversation when it has information to send to a backend server (e.g., the passenger to Seattle checked two bags). The server database running as TCP Server can reply back with the information required to print the baggage routing tags.

  Advantages: Guaranteed and reliable delivery of messages/packets. Strong security available using SSL services. No device driver required.

  Disadvantages: Slightly more difficult to program than UDP or serial (RealPort).

- UDP (User Datagram Protocol)
  UDP is a "connection-less" protocol, meaning that the Digi Connect ME device can be either the initiator or responder at any particular time. UDP is a good choice when the conversation is very structured, with one device making a request and waiting for the reply. Because UDP doesn't guarantee the delivery of messages, using it in situations where the sender doesn't wait for a particular reply before sending the next request may not be ideal. A good choice for UDP communications is when an application is checking online status of a number of remote devices. Each remote device can be connected to a Digi Connect ME module. Because UDP allows multiple destinations for each message, the application can send one request and listen for each remote device to respond.

  Advantages: "Light-weight" networking protocol. Easy to program. No device driver required. Good choice for broadcasting to multiple devices.

  Disadvantages: Delivery of messages/packets is not guaranteed. No security option. Order of messages and replies is not guaranteed.

- Email (SMTP) Alarms
  Email (SMTP - Simple Message Transport Protocol) alarms are a good choice when the Digi Connect ME is used to monitor the status of the device it is connected to and when a simple notification via email is all that is needed. An example of alarm notifications is a network-enabled copier running unattended in a public area. Sensors measuring toner level, paper level, and jams in the paper path can be connected to the general purpose inputs of the Digi Connect ME. When a fault condition occurs, a general purpose input would be signaled and an email would be sent to a service technician requesting assistance.

  Advantages: Alarms sent via email - no programming required. Good choice for monitoring status of device using GPIO (general purpose input/output) lines.

  Disadvantages: Email does not provide a guaranteed reliable communications medium, meaning that email messages sent are not guaranteed to be received.

- Digital Output Control
  The Digi Connect ME can be used to control other devices using the GPIO (digital) outputs. An example of using digital output control is a Connect ME module setting the state of relays from a remote location using the network and the configuration applet.

  Advantages: GPIO outputs controlled using the via the web interface on the Connect ME - no programming required.

  Disadvantages: The communication is manually initiated, meaning the operator must set the output lines when the state needs to change.

### Configuring the Communication Models

To configure the communication parameters for the Connect ME module, use the Web configuration. Run the Device Discovery program, select your Digi Connect ME and choose `Open web interface` in the `Device Tasks` window. A web browser window will open and the configuration applet for the module will be displayed (alternately, you can open a browser window and enter the IP address of the Digi Connect ME module).

- Configure the Connect ME for RealPort
  1. Choose `Serial Ports` from the `Configuration` section of the menu on the left side of the browser.
  2. Choose `RealPort` and make sure the `Enable RealPort Server` box is checked. It is not necessary to configure `Basic` serial port settings since they will be set by the application running the RealPort driver.
  3. Click the `Save` button at the bottom of the window.
- Configure the Connect ME as a TCP Client
  1. Choose `Serial Ports` from the `Configuration` section of the menu on the left side of the browser.
  2. Choose `TCP` and make sure the `Automatically establish TCP connections` box is checked.
  3. If you are using the sample application provided, choose `DCD` in the Connect field. This will initiate the connection when the DCD line is asserted.
  4. Enter the IP address of the TCP Server (the remote device to connect to) in the `Connect To` field.
  5. Enter the port number for the conversation (use `7777` with the sample applications) in the `TCP Port number` field.
  6. Choose `Basic` and set the serial port parameters to match the device connected to port 1 of the Digi Connect ME development board. If you are using the sample applications and a loop-back plug, you can omit this step.
  7. Click the `Save` button at the bottom of the window.
- Configure the Connect ME as a TCP Server
  1. Choose `Serial Ports` from the `Configuration` section of the menu on the left side of the browser.
  2. Choose `TCP` and make sure the `Enable TCP Server` box is checked.
  3. Enter the TCP port number for the conversation in the `Raw TCP Port` field (use `2101` with the sample applications).
  4. Click the `Save` button at the bottom of the window.
- Configure the Connect ME for UDP
  1. Choose `Serial Ports` from the `Configuration` section of the menu on the left side of the browser.
  2. Choose `UDP` and make sure the `Enable UDP Server` box is checked if the Connect ME should receive UDP messages. Make sure the `Enable UDP Client` box is checked if the Connect ME should send UDP messages.
  3. If receiving UDP messages, enter the `Raw UDP Port` value. The default value `2101` should be used for the sample applications.
  4. Connect ME can send UDP messages to one or more destinations. If the Connect ME is sending UDP messages, enter the `IP address` for each destination, enter the `UDP Port` that the destinations are using, and make sure the `Enabled` field is checked for each destination. For the UDP sample application set the `UDP Port` to `7777`. Enter the `Raw UDP Port` value. The default value `2101` should be used for the sample applications.
  5. Click the `Save` button at the bottom of the window.
- Configure the Connect ME for Alarm Notification
  1. Choose `GPIO` from the `Configuration` section of the menu on the left side of the browser.
  2. For each of the GPIO pins used for alarms, set the `Pin` to `in`.
  3. Click the `Save` button at the bottom of the window.
  4. Choose `Alarms` from the `Configuration` section of the menu on the left side of the browser.
  5. Make sure the `Enable sending alarms` box is checked.
  6. Enter the `SMTP server address` of the email server to use. In the `From` field enter the name to use as the email sender.
  7. For each alarm defined, make sure the `Enable alarm` box is checked.
  8. Set the `Trigger condition` for the alarm. To trigger the alarm when the first GPIO line is driven high, set the first checkbox in the trigger condition field to `1`. To trigger the alarm when the second GPIO line is driven low, set the second checkbox in the trigger condition field to `0`.
  9. Enter the `Trigger interval`. When a trigger bounces in and out of alarm state frequently, you can use this setting to reduce the number of email alarms sent. For example, if an input line triggers three times within one second because of bounce, setting the `Trigger interval` to two seconds tells the Connect ME to wait two seconds after the first trigger before looking for the next trigger (i.e., one email alert will be sent instead of three).
  10. If the `Enable reminder notifications` box is checked, emails will be sent at the `Reminder interval` as long as the trigger condition is true.
  11. Enter the `To`, `CC`, `Subject` and email `Priority` fields.
  12. Click the `Save` button at the bottom of the window.
- Configure the Connect ME for Digital Output Control
  1. Choose `GPIO` from the `Configuration` section of the menu on the left side of the browser.
  2. For each of the GPIO pins used for output, set the `Pin` to `out`.
  3. Click the `Save` button at the bottom of the window.
- Configure the Connect ME as SSL (Secure) Server
  1. Choose `Serial Ports` from the `Configuration` section of the menu on the left side of the browser.
  2. Choose `TCP` and make sure the `Enable TCP Server` box is checked.
  3. Enter the TCP port number for the conversation in the `Secure TCP Port` field (use `2601` with the sample applications. Note that the only difference between normal and Secure (SSL) TCP Server is the port number.
  4. Click the `Save` button at the bottom of the window.

### Using the Sample Applications to Exercise the Connect ME

The Digi Connect ME integration kit contains sample applications (in both compiled and source code format) to use with the various communications models supported by the Connect ME module. Before running any of the samples, make sure you have configured the Connect ME module as described in the Configuring Communications Models section.

- Running the Connect ME with RealPort
  1. Make sure the Digi Connect ME is configured for RealPort as described in the Configuring Communications Models section.
  2. Make sure the RealPort driver is installed on the PC.
  3. Plug the diagnostic loop-back plug into port 1 on the Connect ME development board.
  4. From the Windows start menu, browse to the HyperTerminal application. Create a new connection and choose the serial port on the Digi Connect ME in the `Connect using` field. Set the serial port parameters.
  5. From the terminal screen in HyperTerminal you can type characters and should see them echoed back with the loopback connected. You can also use the `Transfer/Send File` feature in HyperTerminal to send and receive data.
- Running the Connect ME as a TCP Client
  1. Make sure the Digi Connect ME is configured as a TCP Client as described in the Configuring Communications Models section.
  2. Open the TCP Server sample application to communicate with the Digi Connect ME module configured as TCP Client. A shortcut is created in the `Programs/Digi Connect Integration Kit/Samples` section of the Windows `Start` menu.
  3. Plug the diagnostic loop-back cable into port `P2` on the Digi Connect ME development board.
  4. You will see an exchange of messages between the Digi Connect ME module and the TCP Server application running on the PC.
  5. See the Readme.html file in the source code directory of the sample for more information.
- Running the Connect ME as a TCP Server
- 1. Make sure the Digi Connect ME is configured as a TCP Server as described in the Configuring Communications Models section.
  2. Open the TCP Client sample application to communicate with the Digi Connect ME module configured as TCP Server. A shortcut is created in the `Programs/Digi Connect Integration Kit/Samples` section of the Windows `Start` menu.
  3. Enter the IP address of the Digi Connect ME module when prompted in the TCP Client sample.
  4. Plug the diagnostic loop-back cable into port `P2` on the Digi Connect ME development board.
  5. You will see an exchange of messages between the Digi Connect ME module and the TCP Client application running on the PC.
  6. See the Readme.html file in the source code directory of the sample for more information.
- Running the Connect ME with UDP
- 1. Make sure the Digi Connect ME is configured for UDP as described in the Configuring Communications Models section.
  2. Open the UDP Serial sample application to communicate with the Digi Connect ME module configured for UDP. A shortcut is created in the `Programs/Digi Connect Integration Kit/Samples` section of the Windows `Start` menu.
  3. Enter the IP address of the Digi Connect ME module when prompted in the UDP Serial sample.
  4. Plug the diagnostic loop-back cable into port `P2` on the Digi Connect ME development board.
  5. You will see an exchange of messages between the Digi Connect ME module and the UDP Serial application running on the PC.
  6. See the Readme.html file in the source code directory of the sample for more information.
- Running the Connect ME with Alarm Notification
  1. Set the switches on `SW1` on the development board to the `IO1`-`IO5` positions. This disables the serial signals and enables the use of all five GPIO pins on the Digi Connect ME module.
  2. Set the switches on `SW2` on the development board to the `High` positions. This is the ungrounded state for the external connector and is the state that you should normally set for `SW2`.
  3. Make sure the Digi Connect ME module is configured for GPIO inputs and that the alarms are enabled as described in the Configuring Communications Models section. For this example, set GPIO #1 to `in` and set an alarm on GPIO #1 that triggers on logical level `1`.
  4. Change switch #1 on `SW2` from `High` to `Low` and back again. This triggers the email alarms defined.
- Running the Connect ME with Digital Output (GPIO) Control
  1. Set the switches on `SW1` on the development board to the `IO1`-`IO5` positions. This disables the serial signals and enables the use of all five GPIO pins on the Digi Connect ME module.
  2. Set the switches on `SW2` on the development board to the `High` positions. This is the ungrounded state for the external connector and is the state that you should normally set for `SW2`.
  3. Make sure the Digi Connect ME module is configured for GPIO output as described in the Configuring Communications Models section. For this example, set all five GPIO pins to `out`.
  4. Choose the `System Information` section of the `Administration` menu of the left side of the browser. Choose the `GPIO` page of the system information screen. As you change the GPIO settings from asserted to unasserted (and click `Set Pins`, you will see the state of the LEDs on the development board change.

## Advanced Topics

### Customizing the Digi Connect ME module

The Digi Connect ME is easily customized and integrated with your product. The integration kit includes several tools to assist with some of the most common customizing tasks.

- Source code for a discovery application is provided. The look and feel of the discovery application can be changed to match the look and feel of your product.
- Device discovery uses a Digi protocol called ADDP (Advanced Device Discovery Protocol) to locate and configure Digi Connect ME modules on the network. A programming library is included in the integration kit to allow you to write applications using ADDP. (The device discovery sample and the Digi device discovery application both link with this library). The interface for this library (".H" file) is located here. The source code for the discovery application is a very good reference for understanding how ADDP works.
- Source code for the Java applet is available upon request. You can choose which of the included settings your customers are able to view and configure through the Java applet. You can also replace Digi logos and product names with your own.

### Administrative Tasks

The Digi Connect ME has several administrative tasks that can be accessed using the Java applet. These tasks include saving and restoring the configuration, restoring the factory default configuration, displaying system information, and rebooting the module.

If you cannot display the Java applet, or if you have compiled your own applet and chose not to include these menus, it is still possible to perform most of these tasks by pointing your Internet browser to the `/admin/administration.htm` page of the module (e.g., if the IP address of the Digi Connect ME module is 192.168.123.100, point the browser to http://192.168.123.100/admin/administration.htm).

- Saving and Restoring the configuration
  Saving and restoring the configuration for the Digi Connect ME can only be done using the Java applet.

  Choose `Backup/Restore` from the `Administration` section of the menu on the left side of the browser. To save the Connect ME configuration to a file on your PC, click the `Backup` button then enter a filename for the backup image. To restore the configuration using a file you previously saved, browse to the backup file and click the `Restore` button.

- Restoring factory default configuration
  Restoring the factory default configuration can be done using either the Java applet or the `admin/administration.htm` page.

  Choose `Restore Factory Defaults` from the `Administration` section of the menu on the left side of the browser, or choose `Factory Default Settings` from the menu on the `admin/administration.htm` page. If you use the `admin/administration.htm` page, you also have the choice of keeping the current IP address for the module. Click the `Restore` or `Restore Now` button. (Note: If you are unable to access the administration page, you can point your browser to `/admin/factory_defaults.htm`).

- Viewing system information and statistics
  Viewing system information and statistics for the Digi Connect ME can only be done using the Java applet.

  Choose `System Information` from the `Administration` section of the menu on the left side of the browser. The `General` page displays the firmware versions, the MAC address, and the CPU and memory information. The `GPIO` page displays the current state of the lines configured as inputs. You can also change the state of any GPIO line configured as an output. The `Serial` page displays the current state of the serial control lines and the statistics for the serial port. The `Network` page shows the statistics for the Ethernet port.

- Rebooting the module
  Rebooting the module can be done using either the Java applet or the `admin/administration.htm` page.

  Choose `Reboot` from the menu. At the prompt, click the `Reboot` button.

- Updating the firmware
  Updating the firmware files can only be done from the `admin/administration.htm` page. Choose `Update Firmware` from the menu and browse to the new firmware file. Choose `Update` to send the new image to the module.

  The name of the firmware file for the embedded operating system ("EOS") typically is `82000856_x.bin`, where `x` represents the release version. The name of the firmware file for the POST (power-on self test) typically is `82000867_x.bin`, where `x` represents the release version. The firmware versions that shipped with this integration kit can be found in the `Factory Defaults` directory of the Integration Kit installation.

- Updating the Java applet and/or HTML pages
  Updating the firmware files can only be done from the `admin/administration.htm` page. Choose `File Management` from the menu and browse to the new file. Choose `Upload` to send the new file to the module.

  The name of the Java applet typically is `ConfigME.jar` and the name of the static index page (HTML page) is `Index.htm`. The index page is displayed if the applet is not available. The applet and index page that shipped with this integration kit can be found in the `Factory Defaults` directory of the Integration Kit installation.

## Supplemental Material

The integration kit includes manuals and documentation to help you easily network-enable your product with the Digi Connect ME module.

- The Hardware Reference Manual contains mechanical and electrical specifications for the Connect ME module, including dimensions, PCB layout suggestions, and connector information, as well as development board connectors, switches and test points
- The User's Guide describes the software configuration options for the Digi Connect ME module. Information about updating the Connect ME software, troubleshooting and saving & restoring configuration settings is also included.

Digi International Inc. | 11001 Bren Road E. Minnetonka, MN 55343 PH: (952) 912-3444 or 877-912-3444 FX: (952) 912-4952