CalAmp LMU Series Protocol Adapter SDK Setup Guide
CalAmp LMU Series Protocol Adapter SDK Setup Guide
Introduction ................................................................................................................................ 2
About the CalAmp LMU-Series ................................................................................................ 2
Installation .................................................................................................................................. 2
Connect the LMU-Series Device .............................................................................................. 2
Configuration and Setup ............................................................................................................. 3
Configure the Server and Protocol Adapter SDK ...................................................................... 3
Configuring the CalAmp Device via SMS protocol .................................................................... 6
Troubleshooting.......................................................................................................................... 8
General Troubleshooting Checklist.......................................................................................... 8
Troubleshooting Guide ............................................................................................................ 8
Compatibility............................................................................................................................. 10
Document Revision History ....................................................................................................... 10
1
CalAmp LMU-Series Protocol Adapter SDK Setup Guide
Introduction
Small devices that are not able to run the ThingWorx EMS or one of the ThingWorx Edge SDKs can still
connect to a ThingWorx Platform by using a Protocol Adapter Listener server. A Protocol Adapter
Listener Server will open a networking port and listen for messages from the small device, while
simultaneously establishing a connection with the target ThingWorx Platform.
When the Protocol Adapter (listener server) receives a message from the small device, it will decode the
message from the device’s native reporting protocol into Thingworx-ready properties and events before
transmitting them to the target ThingWorx Platform.
The small device must be able to make a network connection to the Listener server, and the Listener
server will also need to be able to make a connection to the ThingWorx Platform. The Protocol Adapter
listener can be run on the same server as the ThingWorx Platform, but it is not a requirement. Any
server that can be reached by the small device and can also reach the ThingWorx Platform is suitable for
use.
The LMU-Series devices are flexible and economical mobile GPS tracking and reporting devices,
manufactured by CalAmp Corporation.
While the LMU-Series devices do not support direct installation of the ThingWorx Edge SDK or
ThingWorx Edge Microserver, the devices may still be connected to a ThingWorx Platform via a Protocol
Adapter SDK (listener server). The Platform may interpret the data after it is translated by the Protocol
Adapter.
Installation
Setup of the CalAmp LMU-Series will require the use of an activated SIM card with a data plan, and
either a control center or mobile device to send SMS messages to the device, or a serial cable
connection to the device. For establishing a serial connection, refer to the Hardware and Installation
Guide provided by CalAmp for your device.
Please note that this guide was written for a computer running Microsoft Windows. Refer to the
Troubleshooting section of this guide for help with frequently asked questions.
1. This guide will follow the procedure for configuring the device using a series of specially-formatted
SMS message commands. Alternatively, you may choose to set up the device by using a serial
2
CalAmp LMU-Series Protocol Adapter SDK Setup Guide
connection from a PC via a terminal program such as PuTTy or HyperTerminal. Refer to the
Hardware and Installation Guide for the LMU device provided by the manufacturer for more detail.
2. Insert the SIM card into the LMU device, connect it to a power supply, plug in the battery, and
confirm that the device powers up.
3. Using either a mobile device or a SIM control center such as Jasper Control Center, send a
command to the device to verify that it is able to send and receive SMS commands. Send the
following command to the device via SMS:
!R0
4. The device should respond to the sender after a few minutes with a message such as the following:
APP:081 8.3d
COM:0
GPS:No Time Sync
INP:11100111 13.7V
MID:4141000100 ESN
INB:207.7.101.227:20500 LMD
In the above sample response, the INP: line shows that a destination server and port have been set,
but the COM:0 line indicates that an APN has been set.
Your response may differ from this, especially if no destination server address has been set yet.
1. Use of this device and a Protocol Adapter SDK will require the setup and use of a remote server. The
server should be configured to accept inbound connections from the device.
2. The Protocol Adapter SDK for the CalAmp device is included as part of this Starter Kit. Locate the zip file
containing two .jar files and a config.json file. The config.json file must be configured with the
connection parameters of your server. It must be configured both to accept incoming connections from
the device and to connect itself to the ThingWorx Platform, and it should be located on the server
hosting your Protocol Adapter SDK.
To connect to a ThingWorx Platform, three unique pieces of information are needed (for a non-SSL
connection): Server address/url, connection port, and an AppKey.
3. Open the config.json file and edit the information contained in the file for the ConnectionServerSettings
(incoming connections from the device):
"ConnectionServerSettings": {
3
CalAmp LMU-Series Protocol Adapter SDK Setup Guide
"isMultiRow": false,
"name": "ConnectionServerSettings",
"description": "Connection server / socket settings",
"rows": [{
"socketProtocol": "UDP",
"connectionServerThingName": "testConnectionServer",
"socketPort": 25505
}],
You should use this port (25505) and the UDP protocol for this starter kit and the LMU-Series devices.
4. Locate the section in config.json entitled ThingWorxConnectionInfo, and modify the information so that
the port, APIKey, and server url are correct. These parameters should specify where your ThingWorx
Platform Server is located. If your platform is hosted on the same server where the Protocol Adapter
SDK will be running, you should specify “localhost” for thingWorxServer.
"ThingWorxConnectionInfo": {
"isMultiRow": false,
"name": "ThingWorxConnectionInfo",
"description": "ThingWorx Server Connection Settings",
"rows": [{
"thingWorxServerPort": 80,
"thingWorxServerAPIKey": "6f14e0b8-c00e-453a-940d-5d43157ae2e6",
"thingWorxServer": "localhost",
"thingWorxServerTimeout": 60000,
"thingWorxServerUseSSL": false
}],
5. Save and close the config.json file. Save and close the config.json file.
Verify that your ThingWorx Platform is up and running at the location specified in the config.json file.
Extract all the contents of the zip file to a location on your server, and run the following command
prompt command (on a Windows server):
If the configuration information is correct, the console should display messages similar to the following
after a few seconds:
22:09:28.200 [NettyClient-NIO-1] DEBUG c.t.c.c.e.DispatchingClientEndpoint - RESPONSE received [endpoint
id: 0, duration: 11] ResponseMessage [requestId: 2, endpointId: -1, sessionId: -1, code: STATUS_SUCCESS,
multipart: false, packet #: 0, total packets: 0]
22:09:28.204 [Thread-4] INFO c.t.d.server.SocketListener - Listening on UDP port 25505
22:09:28.214 [Thread-5] DEBUG c.t.c.c.e.m.CommunicationEndpointMonitorTask - Initializing
CommunicationEndpoint Connection Monitor...
22:09:28.218 [Client-EndpointMonitor-2] DEBUG c.t.c.c.e.m.CommunicationEndpointMonitorTask -
CommunicationEndpoint Monitor - checking for disconnected endpoints
22:09:42.859 [Client-EndpointMonitor-1] DEBUG c.t.c.c.e.m.CommunicationEndpointMonitorTask -
CommunicationEndpoint Monitor - checking for disconnected endpoints
22:09:43.219 [Client-EndpointMonitor-2] DEBUG c.t.c.c.e.m.CommunicationEndpointMonitorTask -
CommunicationEndpoint Monitor - checking for disconnected endpoints
22:09:57.862 [Client-EndpointMonitor-1] DEBUG c.t.c.c.e.m.CommunicationEndpointMonitorTask -
CommunicationEndpoint Monitor - checking for disconnected endpoints
4
CalAmp LMU-Series Protocol Adapter SDK Setup Guide
If there is a problem connecting to the Platform, the log file will look like this:
6. Once the Protocol Adapter has successfully connected to the target ThingWorx Platform, the
DeviceSimulator can be used to send simulated device messages to the codec listener (if desired).
Otherwise, you may proceed to configuring the CalAmp device to connect to the running Protocol
Adapter SDK.
If you choose to use the device simulator to simulate a connection from a device, run the following jar
file with the following command:
This will begin sending a UDP packet every ten seconds to the Protocol Adapter SDK.
This connection may be verified on your ThingWorx Platform under Remote Monitoring.
5
CalAmp LMU-Series Protocol Adapter SDK Setup Guide
1. With the CalAmp device plugged in, activated, and running (with cellular signal), log in to a Jasper Control
center or have a mobile device ready to send SMS messages. (Note that the device may also be
configured by using a serial cable connection to a PC along with a terminal program. Refer to CalAmp’s
Hardware and Installation guide for assistance in this type of configuration).
From the handset or control center, send an SMS message to the LMU device:
!RP,2319,0,ddd.ddd.ddd.ddd
!RP,768,0,ddd.ddd.ddd.ddd
!RP,769,0,ppppp
Where ddd.ddd.ddd.ddd is the publicly addressable IPV4 address of your Protocol Adapter listener
server, and ppppp is the UDP port number configured in the config.json file earlier.
!RP,2319,0,52.24.140.88
!RP,768,0,52.24.140.88
!RP,769,0,25505
You should receive a response from the device if it sets successfully such as “OK”.
Send another SMS to confirm that the settings have been configured:
!RP?2319,0
!RP?769,0
And the device should respond again with the information set concerning the IP address and UDP Port
the device has in memory for connecting to the Protocol Adapter listener server.
!RC
At this point, the CalAmp device should be reporting to the Protocol Adapter SDK after a few minutes,
assuming the configuration information is correct and the server accepts incoming connections from the
device on the port specified.
6
CalAmp LMU-Series Protocol Adapter SDK Setup Guide
7
CalAmp LMU-Series Protocol Adapter SDK Setup Guide
This confirms that your device is successfully connected to the ThingWorx Platform.
At this point, you may bind the remote things and pull data from them as required.
Note: Depending on the device, the Protocol Adapter SDK may need to be modified slightly in order to properly
parse data messages from the particular CalAmp device you are using.
Troubleshooting
1. Is there a SIM card in the device? (not applicable for most CDMA devices)
2. is the device programmed with the proper APN?
3. Is the device programmed to send data to the proper Codec listener host and port?
4. Is the SIM card working? (not applicable for most CDMA devices)
5. Is the device working?
6. Is the device connected to the network?
7. Is the APN correct?
8. Is the Protocol Adapter SDK Running?
9. Is the Protocol Adapter listening on the correct port?
10. Is the port open for traffic?
11. Is the Protocol Adapter SDK communicating with the ThingWorx Platform?
12. Does “message processing” terminate or otherwise become stuck in the Codec Listener during
the parsing phase?
Troubleshooting Guide
Problem Solution(s)
1. The CalAmp device will not 1. Verify that the SIM card in the device is properly inserted and activated with both an SMS
respond to SMS commands. plan and a data plan.
2. Verify that the device has cellular signal. Try moving to an area with better cell reception.
Use the LED lights on the device to confirm that it has signal; refer to the Hardware &
Installation Guide for the unit provided by CalAmp to address this issue further.
2. The CalAmp device cannot 1. Check firewalls and port forwarding on the Protocol Adapter server to verify that incoming
connect to the server connections are allowed.
8
CalAmp LMU-Series Protocol Adapter SDK Setup Guide
2. Check the network status of the device. If a device has no network connectivity, then it is
not going to reach the codec. There are many ways to check the network connectivity
and it will be different for every device. Here is a list of things to try that most devices will
have available:
-Is there a way to check signal strength/csq?
-Can it check to see if it generated an IP?
-Are there LEDs on the device indicating the status of network connectivity?
Checking this will result in one of two things you need to check next:
• If this is the case, then you need to make sure the device and SIM card are
working properly.
2. There is network connectivity, but there are still no messages making it to the protocol
adapter SDK listener:
• If this is the case, you will need to check if the device is configured properly to
send messages in the proper format.
• Next you will want to debug the port settings to make sure the ports are both
open for traffic, as well as listened to properly by the protocol adapter.
Note: It is possible to have a signal strength without being connected to the network.
Keep this in mind. CSQ is not the only thing you need to know about to check the
connectivity. If this is the case, it is usually an APN issue.
In order to use a SIM card in a device, it is important to know a little information about the
SIM card and the device:
2. Do you need a username and password for it, and if so, do you know it?
Even if all of this is correct, there may still be issues. If this is true, you should follow
these steps:
This can be something you have worked with before successfully and know works. Put
the SIM you are attempting to use into the device and configure the APN settings. If the
device gets network connectivity then the SIM is working fine and you have the correct
APN information. Move on to step 2 below. If it does not get connectivity, then your
problem is a bad SIM card and you need a new one.
Put a known working SIM into the device and try to get network connectivity on it. If you
still cannot access the network, then either the device is broken, or you need to contact
someone from the manufacturer to verify proper configuration.
This will vary greatly by device, but the general process is still the same. Make sure the
device is using the proper data format (UDP, TCP, HTTP) and note that some devices
have multiple versions (UDP w/ ACK, UDP w/ Server commands, etc.) Make sure you
use the General Protocol Adapter SDK user guide to identify what the setting should be.
9
CalAmp LMU-Series Protocol Adapter SDK Setup Guide
There are also sometimes other settings that are required; for instance, in some devices,
you need to set the Optional API header to include the bitmask and event type. These
directions can be found in the manufacturer’s user guide. If the format is set correctly,
then make sure the device is actually sending data. This could be a heartbeat message,
or some event that you can control. It just needs to be something to result in data being
sent to a specific host and port.
If the device has network connection, and is configured correctly, but is still not reaching
the codec, then the next step is to check the port settings. This requires a little bit of
information:
3. The CalAmp device will not 1. Refer to the Hardware and Installation Guide. Most CalAmp devices require a 12v power
power on source, with the pins properly connected as specified in the guide.
Compatibility
This guide has been tested for compatibility with the device and the following ThingWorx Platform and
operating system:
10