Welcome to NTCIP Proxy’s documentation!¶
Introduction¶
Since 2014, as part of our “Totally connected. Totally protected.” promise, Solar Technology has been including remote control with many of our products, including:
Message boards based on the third-generation touchscreen controller within the United States and canada.
Message boards based on the second-generation touchscreen controiller with an included Solarcomm unit.
The Solarcomm Universal device, which is used to connect third-party NTCIP equipment to our network and Command Center NTCIP.
The Solartech NTCIP proxy provides a gateway between third-party NTCIP client software and our private network, allowing us to to provide access to this third party software as if it was located on the private network. The NTCIP proxy also compresses NTCIP packets to minimize the amount of bandwidth required to be sent to the NTCIP device.
This explains how to configure your NTCIP client software to communicate with NTCIP devices using the NTCIP proxy, and how to diagnose problems with such communication.
The NTCIP proxy is also used by Command Center NTCIP to communicate with NTCIP-based message boards. Configuration of these connections is automatic, and hence outside the scope of this document. However, you may see communication between Command Center NTCIP and devices show up in the NTCIP proxy logs.
Definitions¶
With NTCIP Proxy, there are four components that participate in an NTCIP exchange.
- Client
The Client is the NTCIP client software that initiates an NTCIP request, and receives the NTCIP response when a request is completed. This is generally running on a computer - a workstation or server - that you control.
- Server
The NTCIP Proxy Server is one of the servers maintained by Solar Technology in our data centers. When a request is received by a server, that server checks to see if it can answer the request using server-side data. If it can, a response is sent to the client. Otherwise, the request is compressed and sent on the remote.
When a response comes back from the remote, it is decompressed and sent to the client.
- Remote
The remote may be a physical Solarcomm device, or a program running on the third-generation touchscreen controller. The remote receives compressed requests from the Server, and passes them to the NTCIP device.
When the responds comes back from the device, it is compressed and sent back to the server.
- NTCIP Device
The NTCIP device is a message board or other NTCIP-capable device. Standard NTCIP requests are sent to the device, and responses from the device are relayed back through the remote and server to the client.
Configuration¶
Configuring the Device¶
Solar Technology Devices¶
If you have a supported Solar Technology device (a third-generation touchscreen controller or second-generation touchscreen controller with Solarcomm), configuring the device can be done through Command Center.
Open the device in Command Center, then on the individual unit management page go to the “CMS Unit” menu and choose “Set the Unit’s NTCIP/UTMC Password…:”. This will set the NTCIP community string which must be between 8 and 16 characters.
Next, use the CMS Unit menu, “NTCIP Control” submenu to set the unit to Enabled/Central.
The unit is now set up for NTCIP control.
Solarcomm Universal - Default Configuration¶
For a Solarcomm Universal remote that can be connected to a device using the default configuration (NTCIP over UDP on port 161 over Ethernet, IP address configured automatically by DHCP, community string of ‘administrator’), configuring the device requires a small number of steps, that may vary by device.
Enable to device’s ethernet port, configured to obtain an IP address automatically using DHCP.
Set the NTCIP community string to “administrator”.
Enable NTCIP in central mode.
For instructions on how to do this, please refer to your device’s documentation.
Solarcomm Universal - Manual Configuration¶
Apart from the default (NTCIP over UDP on port 161 over Ethernet), Solarcomm Universal supports a number of other configurations, including:
NTCIP over UDP on any port over Ethernet.
NTCIP over TCP on any port over Ethernet.
NTCIP over PMPP over TCP on any port over Ethernet.
NTCIP over PMPP over Serial.
The community string used with the device may also be changed.
These configurations may be through the NTCIP proxy web interface. To do so:
Log in with your Command Center organization, username, and password.
Find the device you’re interested in, and click the gear icon to configure it.
Change the settings, and click save.
Changes will be synchronized immediately
Configuring the Client Software¶
To configure your NTCIP client software to access the NTCIP proxy, you’ll need to find the settings for that unit. To get these settings:
Log in with your Command Center organization, username, and password.
Find the device you’re interested in, and click the “Info” link.
This will bring you to a page with contact information that can be used by NTCIP client software to connect to the NTCIP proxy server.
The default configuration uses a DNS-based IP address (ntcip.solartechnology.com) UDP port 161, and a device-specific community string.
Alternate configurations exist for client software that cannot accept the default configuration. Click “Alternate Client Configuration” on the info screen to access this information. There are two main cases where this can be used.
If the software does not accept a DNS-based IP address, numeric IP addresses can be used at the cost of redundancy.
If the software requires a single community string to be used (rather than a per-unit community string), an alternate port number and community string can be used instead.
Troubleshooting¶
Diagnostic Test¶
The first step in troubleshooting is to perform a diagnostic test:
Log in with your Command Center organization, username, and password.
Find the device you’re interested in, and click the “Test” link.
This performs three diagnostic tests.
Server to Remote Communications Test¶
The first test checks that the server can communicates with the remote (the solarcomm device or message board). If this fails, the likely cause is that the remote is not turned on, the antenna is not connected, or the remote is not in an area with cellular coverage.
Remote to Node Communications Test¶
The second test checks that the remote can communicate with the message board, by retrieving the globalTime.0 node from the device.
There are a number of reasons why this test could fail. On all devices, the test could fail if the device is not configured to respond to NTCIP requests. For Solarcomm devices, the test could fail if the Solarcomm remote is not connected to the NTCIP device, or the NTCIP device is configured incorrectly or turned off.
End to End Test¶
The End to End test simulates a properly-configured NTCIP client making a request for the globalTime.0 node. The request is sent to the server, remote, and device, and the device’s response is returned back through the remote and server to the client.
While (short of conditions changing) we don’t believe this test can fail when the prior two tests succeed, we believe that the End to End test provides a valuable data point - it shows us that the NTCIP proxy is working, and the client configuration is the problem. Logs can then be used to further troubleshoot the problem.
Should the End to End test ever fail while the other two tests succeed, please immediately contact us so we can troubleshoot the problem.
Logs¶
The default log view, and the most useful one for troubleshooting purposes, is the view of exchanges originating from your current IP address. To get to this page:
Log in with your Command Center organization, username, and password.
Click “log” in the bar at the top.
You should visit this pages from the computer making NTCIP requests. If your software has a client-server setup, where your local server makes NTCIP requests, you’ll want to access this page from your local server.
The logs show information about each NTCIP exchange. The information is color-coded:
- Blue
The request is currently in progress.
- Red
The request failed for a communications-related issue. This could be an incorrect community string or unreliable communications causing the response to time out or be corrupted.
- Orange
The request succeeded, but contain an NTCIP error. This is caused by a compatibility issue between your client software and your NTCIP device, with NTCIP proxy simply relaying the error condition.
- Green
The request succeeded completely. If your client is still having problems, it’s likely due to the client not being able to control that type of NTCIP device.
The header line of each exchange contains:
On the left, the IP address originating the exchange.
In the center, the type of the request.
On the right, the name of the unit, and the serial number of the remote.
The first line of the body contains:
A textual description of the success or failure of the operation. This can tell you what went wrong, if something did.
On success, a description of bandwidth usage: How large the SNMP request and response were, how much data was sent via the proxy, and how much data our compression saved you. (When a request is answered on the server, we can save you 100%.)
The second line of the body contains the type of the request, the community strings, and a description of any SNMP errors that were returned.
Finally, this is followed by a table giving the OIDs requested and the data that was sent or received.
Other Logs¶
There are two other kinds of logs that can be accessed. The “All IP Addresses” log is accessed from the log page, and shows all exchanges devices in your organization. The device log can be accessed by clicking “Log” on the device list, and shows exchanges with a particular device.
Both of these only track exchanges for which a device in your organization can be located, and so are less useful in troubleshooting problems that may be caused by an invalid community string.
Usage¶
The NTCIP proxy uses a bandwidth pool to prevent a runaway NTCIP client from consuming excessive amounts of bandwidth. The current limits are 2.5 megabytes per month for Solartech message boards, and 5.0 megabytes per month for Solarcomm Universal devices.
The bandwidth is managed by a pool that is depleted by successful NTCIP exchanges, and replenishes at a fixed rate over time. When the pool is fully depleted, requests will be rejected with a genError until the pool replenishes to the 2 kilobyte level.
Solar Technology technical support is capable of manually resetting the bandwidth pool to return to normal operations once the excessive usage has been eliminated.
Monitoring Usage¶
The device list displays the usage over the past 24 hours and 7 days for each NTCIP device. When usage exceeds the regeneration rate for these either time period, the usage number will turn red. When the usage numbers are red, the bandwidth pool will eventually deplete, and so the number of NTCIP exchanges should be reduced.
The device list also has links to a Usage page for each device. The usage page shows historical usage, the current byte pool, and the replenishment rate.
Compression¶
The Solartech NTCIP proxy uses compression to reduce the amount of data that is transferred over the cellular networks. We pass the savings from compression on to our customers - the bandwidth pool is only depleted by data that is actually sent over the air.
There are two forms of compression that are used. The first is to eliminate redundant data in NTCIP exchanges, like the duplication of OIDs between requests and responses, or the relatively long OID prefix at the start of all NTCIP OIDs.
The second form of compression is to answer GET queries with data stored on the server, where possible. This is currently done with essLatitude and essLongitude queries. Message boards and Solarcomm Universal devices send position information to the server, and so queries of these positions do not require any data to be transferred via the cellular network - hence, an request that only queries essLatitude and essLongitude does not deplete the bandwidth pool.
Position information is sent to the server every five minutes when the device is moving or has recently moved. (So requests for the position may yield a position that is slightly out of date.) NTCIP proxy always returns a position given by the GPS connected to the third-generation touchscreen controller or Solarcomm.
Security¶
The NTCIP proxy is designed with security in mind. All links between our servers and the device are either encrypted or physically secure. When combined with an IPSEC tunnel between the NTCIP client and the NTCIP proxy servers, our solution achieves end-to-end security.
In our terminology:
The client is the device that initiates NTCIP requests.
The servers are the computers, located in our data centers, that accept NTCIP requests and proxy them to our private network.
The device is an NTCIP capable messageboard.
Client to Server¶
As NTCIP is not encrypted by default, securing the link between client and server requires setting up a VPN tunnel. Solar Technology supports IPSEC tunneling using IKEv1 or IKEv2, with the precise cyphersuite chosen at the time of tunnel setup.
We also support unencrypted communications, with the client being responsible for any intercepted traffic.
If you’d like to establish an encrypted tunnel, please contact technical support so we can begin the process.
Server to Device¶
In our model, the device itself is only reachable through a private network that can be accessed from our servers. This protects the device from generic exploits, as it can only be accessed through known protocols. To compromise the device would either mean compromising our servers, or guessing the secure community string used to control the device.
Once the traffic leaves our servers, it’s sent through an encrypted tunnel to our carrier partners. They re-encrypt the data as it passed through their network, and when the data is transmitted over the air to the device’s built-in cellular modem.
Responses are handled similarly, but in the reverse direction.
In a Solar Technology message board with the third-generation touchscreen controller, the cellular modem is built in to the controller itself, and hence no interception of the NTCIP data is possible.
When a Solarcomm unit is used, we expect the Solarcomm unit, the NTCIP device it is connected to, and the Ethernet or serial cable used to connect these devices to be placed in a physically secure enclosure. This physical security prevents traffic on the unencrypted link from being intercepted.
API¶
To bridge web technologies and NTCIP, we provide web-based APIs.
Change Message¶
This API connects to a message board, defines a message (message 3-1, the first changeable message), and activates that message.
This service is available at the URL:
https://ntcip.solartechnology.com/api/change_message
It takes the following parameters:
- address
The IP address of the message board. If omitted, this defaults to ntcip.solartechnology.com
- community
The community string to use.
- multi
A MULTI string giving the message to define. This is an ascii string, containing text and MULTI tags. Consult NTCIP 1203 for a full reference, but some useful tags are:
- [nl]
New line.
- [np]
New page.
This returns a JSON object, which has one of the following two fields defined.
- error
A human-readable error message.
- result
Indicates that the message was successfully set.
An example request is:
https://ntcip.solartechnology.com/api/change_message?community=000011-dgw9JR5CW&multi=test[nl]1234
(This may or may not work, depending on how we have our test unit set up. Please contact support to ensure access to a test unit.)