Cogent DataHub software

Version 10.0

May 15, 2024

A real-time database used to aggregate and distribute process data among sources and users across secure connections.


Table of Contents
1. Installation
1.1. System Requirements and Installation
1.2. Installing Licenses
1.3. Installing as a Service
1.4. Performing a Silent (Unattended) Install
1.5. Upgrading to a new version
1.6. Installing over previous versions
1.7. Downgrading to a previous version
1.8. Configuration Files
1.9. Backing Up or Moving a DataHub Installation
1.10. Known Issues
1.11. FAQ
2. Getting Started
2.1. Running the DataHub Program
2.2. Test with simulated data
2.3. Connect to an OPC DA server
2.4. Connect from an OPC DA client
2.5. Test MQTT
2.6. Connecting to InfluxDB
2.7. Custom Connections
2.8. Performance Limitations
2.9. Troubleshooting
2.9.1. Reporting Problems
2.9.2. Tools
3. Properties Window
3.1. For All Options
3.2. General
3.3. OPC UA
3.4. OPC DA
3.5. OPC A&E
3.6. Tunnel/Mirror
3.7. Bridging
3.8. Redundancy
3.9. Database
3.10. Web Server
3.11. DataHub WebView
3.12. MQTT Client
3.12.1. Make the Connection
3.12.2. Exchange Data
3.12.3. Pre-Configured Connections
3.12.3.1. Azure IoT Hub
3.12.3.2. Google IoT
3.12.3.3. AWS IoT Core
3.12.3.4. Sparkplug
3.13. MQTT Broker
3.14. Modbus
3.15. External Historian
3.15.1. General Configuration
3.15.2. Connection Configuration
3.15.3. Supported Historians
3.15.3.1. Amazon Kinesis
3.15.3.2. AVEVA Historian
3.15.3.3. AVEVA Insight
3.15.3.4. InfluxDB V1
3.15.3.5. InfluxDB V2
3.15.3.6. OSIsoft PI
3.15.3.7. REST Client
3.15.3.8. Tunnel (Pull)
3.15.3.9. Tunnel (Push)
3.16. Notification
3.17. InfluxDB
3.17.1. Configuration
3.17.2. Grafana
3.17.3. Chronograf
3.17.4. Advanced Topics
3.18. Email/SMS
3.19. Camera
3.20. System Monitor
3.21. DDE
3.22. Historian
3.23. Quick Trend
3.24. Remote Config
3.25. Scripting
3.26. Security
3.27. Licenses
4. Other Windows and Programs
4.1. Data Browser
4.2. Connection Viewer
4.3. Event Log
4.4. Script Editor
4.5. Script Log
4.6. DataSim - a data simulation program
4.7. DataPid - a PID loop data simulation program
4.8. Remote Config
4.8.1. Preparation
4.8.2. Configuring a Local DataHub Instance
4.8.3. Configuring a Remote DataHub Instance
4.9. Service Manager
5. Tunnelling OPC DA
5.1. Introduction
5.2. Configuring the DataHub instance for the server
5.3. Configuring the DataHub instance for the client
5.4. Testing the connection
5.5. Combinations
5.5.1. Multiple connections
5.5.2. Bridging
5.5.3. Partial data sets
6. Tunnelling Scenarios
6.1. Tunnelling - Firewalls Open
6.2. Tunnelling - One Firewall Closed
6.3. Tunnelling - Both Firewalls Closed, with DMZ
6.4. TCP Ports and DataHub Tunnelling
7. OPC UA Connections
7.1. Introduction
7.2. Acting as an OPC UA Client
7.3. Acting as an OPC UA Server
7.4. Endpoints and Discovery
7.5. Security
7.6. Certificates
7.7. OPC UA to DA Conversions
7.8. OPC A&C to OPC A&E Conversions
7.9. Object Model
7.10. OPC UA Methods
7.11. Restricting Connections
7.12. OPC UA Test Client and Server
7.12.1. Using a Test Client
7.12.2. Using a Test Server
7.13. Troubleshooting
7.13.1. Endpoint URLs
7.13.2. Error Messages
7.13.3. Expired LDS certificate
8. Bridging
8.1. Introduction
8.2. Configuring Bridges
8.2.1. Point-to-point configuration
8.2.2. Making transformations
8.3. Creating New Points
8.4. Configuring Many Bridges
8.5. Bridging Scenarios
8.5.1. Bridging Local Servers
8.5.2. Bridging Remote Servers
8.5.3. Creating Data Sets
8.5.4. Bridging to Excel
8.5.5. Bridging and Tunnelling
9. Using Redundancy
9.1. Typical Scenarios
9.2. Configure the Switch
9.3. Troubleshooting
9.4. Multiple Redundant Pairs
9.5. Warm Standby
9.6. Special Cases Q&A
10. Write to a Database
10.1. Introduction
10.2. Quick Start
10.3. Configuring the Queue, Store and Forward
10.4. Setting up the DSN (Data Source Name)
10.5. Configuring a Database Table
10.6. Key Columns
10.7. Assigning a Trigger
10.8. Setting Trigger Conditions
10.9. Configured Actions
11. Query a Database
11.1. Introduction
11.2. Quick Start
11.3. Setting up the DSN (Data Source Name)
11.4. Configuring a Database Query
11.5. Assigning a Trigger
11.6. Setting Trigger Conditions
11.7. Configured Actions
12. Using the Web Server
12.1. Introduction
12.2. Configuring the DataHub Web Server
12.3. Using ASP to Query a Database and Display Results
12.4. Connecting Browser Applications
12.4.1. ASP Document Requests
12.4.2. WebSocket Connections
12.5. ASP File Locations
13. Using MQTT
13.1. Connecting MQTT Clients with the DataHub MQTT Broker
13.2. Making MQTT Client Connections
13.3. MQTT Advanced Parser Tutorial
13.3.1. Example - Part One
13.3.2. Example - Part Two
13.3.3. Example - Part Three
13.4. MQTT Advanced Parser Reference
13.4.1. Overview
13.4.2. Receive Format
13.4.2.1. Testing a Receive Format
13.4.2.2. Script Execution
13.4.2.3. Topic Name Manipulation
13.4.2.4. Initialization Script
13.4.2.5. Parser Script
13.4.3. Common Formulas
13.4.4. Publish Formats
13.4.5. Exporting, Importing and Duplicating Parsers
13.5. Broker $SYS Topics
14. Using the External Historian
14.1. Typical Scenarios
14.2. Connecting
14.3. Store and Forward
14.4. Tunnel (Push)
14.5. Receiving Side
14.6. Tunnel (Pull)
14.7. Using a DMZ
15. Security
15.1. How to Configure
15.2. SSL Encryption
15.2.1. SSL Certificates and Firewalls
15.2.2. Editing OpenSSL ciphers and options
15.2.3. Modifying SSL Security Levels
15.3. User Authentication
15.4. Authorization and User Permissions
15.5. Permissions for the DataHub Command Set
15.6. Passwords
15.7. Tunnelling Security - Best Practices
16. Making Notifications
16.1. Configure a Notifier
16.2. Define a Template
16.3. Bind a Variable
16.4. Twilio
16.5. OPC A&E
16.6. Multiple Variables
16.7. Multiple States
16.8. A&E Event Settings
16.9. Regular Expressions
17. Email and SMS
17.1. Introduction
17.2. Configuring the Mail Server
17.3. Sending a Test Message
17.4. Defining the Email Message
17.5. Assigning a Trigger
17.6. Setting Trigger Conditions
17.7. Configured Actions
17.8. Sending SMS Text Messages
17.9. HTML Message Examples
17.9.1. An HTML Message with Embedded Data Points
17.9.2. An HTML Message with a Table Created in Code
17.10. Dynamically Changing Email Subjects and Recipients
18. System Monitor
18.1. Introduction
18.2. Configuring the System Monitor
18.3. Monitoring Systems Across a Network
19. Excel Connections
19.1. Getting Data into Excel
19.1.1. Method 1 - Drag and Drop using DDEAdvise
19.1.2. Method 2 - Excel Macros using DDERequest
19.1.2.1. Create a macro
19.1.2.2. Add a Control Button
19.1.2.3. Receive the data
19.2. Getting Data out of Excel
19.2.1. Method 1 - Configuring DDEAdvise loops in the DataHub instance
19.2.2. Method 2 - Writing Excel macros that use the DDEPoke command
19.2.2.1. Create a macro
19.2.2.2. Add a Control Button
19.2.2.3. Send the data
19.2.2.4. Additional Pointers
19.3. Networking Excel
19.4. Working with Ranges
19.4.1. Getting a Range out of Excel
19.4.2. Getting a Range into Excel
19.4.3. Sample Excel Macros for Arrays
19.5. Basic Trouble-Shooting for Excel Connections
20. DataHub Scripting
20.1. Tools
20.2. DataHub ODBC (Open Database Connectivity) Scripting
20.3. DataHub Windows Scripting
21. Working With Data
21.1. Data Points
21.1.1. Creating New Points
21.1.2. Deleting Points
21.1.3. Viewing Data Points
21.1.4. Point Size Limits
21.1.5. Data Types
21.1.6. Coercing a Number to a DATE Type
21.2. Data Communication Concepts
21.2.1. Send and Receive Data
21.2.2. Client - Server
21.2.3. Synchronous and Asynchronous Communication
21.3. Data Exchange Protocols
21.3.1. OPC Protocol
21.3.2. DDE Protocol
21.3.3. Tunnelling/Mirroring
21.3.4. The DataHub APIs
21.4. Data Organization
21.4.1. Data Domains
21.4.2. Assemblies, Subassemblies, Attributes, and Properties
21.4.3. Attributes and Types
21.4.4. Example 1: Attributes and Types
21.4.5. Example 2: Private Attributes
22. Optimizing Data Throughput
22.1. Binary Mode Tunnel/Mirror (TCP) Connections
22.2. Tunnel/Mirror (TCP) Heartbeat and Timeout
22.3. Old Value Queuing
22.4. Un-Buffered Delivery
22.5. Screen Output
22.6. CPU Saturation
22.7. How to Optimize
22.7.1. Tunnel/Mirror (TCP) connections
22.7.2. DataHub C++ API
22.7.3. Gamma scripts
23. Using DataHub Commands
23.1. Command Syntax
23.2. Return Syntax
23.3. Sending Commands by TCP
Cogent DataHub Command Set
acksuccess — tells the DataHub instance to return success messages.
add — adds a value to a point.
alias — creates an alias point for an existing point.
alive — tells a DataHub instance that the client is running.
append — appends a string to the value of a point.
assembly — creates an assembly.
attribute — creates an attribute.
auth — requests authentication for a client.
authreload — is new, not yet documented.
auto_create_domains — automatically adds domains requested by clients.
auto_timestamp — adds timestamps to unstamped changes.
bridge — creates a bridge between two points.
bridge_remove — deletes a bridge.
bridge_remove_pattern — deletes all bridges that match a pattern.
bridge_transform — modifies an existing bridge.
cforce — creates a point and forces a value to be written to it.
cread — creates and reads a point.
create — creates a new point.
create_domain — creates a new domain.
creport — creates a point and requests notification of changes.
cset — creates a point and assigns it a value.
cwrite — creates a point and writes information to it.
DDEAdvise — sets up the item for a DDEAdvise connection.
DDEConnect — makes a connection to a DDE service and topic.
DDEDisconnect — disconnects and discards a DDE connection.
DDEExcelUnicode — accepts Unicode characters in strings in Excel.
DDEInit — initializes the a DataHub instance to act as a DDE server.
DDEService — assigns a DDE service name.
DDEUnadvise — removes an item from a DDE connection.
DDEUnadvisePattern — removes multiple items from a DDE connection.
DDEUnadvisePoint — removes an item from a DDE connection, by its point name.
debug — sets the debug level.
defaultprop — sets a default type for a property.
delete — deletes a point—use with caution.
div — does division on the value of a point.
domain — identifies the client domain name.
domain_bridge — configures a redundancy set.
domain_bridge_enable — enables or disables the Redundancy feature.
domain_bridge_prefer — specifies a preferred source for a Redundancy connection.
domain_bridge_refresh — refreshes a Redundancy connection.
domain_bridge_remove — removes a Redundancy connection.
domains — lists all domains in a DataHub instance.
dump — writes the entire content of a DataHub instance to a file.
enable_bridging — enables or disables bridging capabilities.
enable_dde_client — enables or disables DDE client capabilities.
enable_dde_server — enables or disables DDE server capabilities.
enable_domain_bridging — enables or disables domain bridging capabilities.
enable_opc_client — enables or disables OPC client capabilities.
enable_opc_server — enables or disables OPC server capabilities.
enable_scripting — enables or disables scripting capabilities
error — sends an error with an error string.
execute_plugin — executes a plugin. (experimental)
exit — shuts down a DataHub instance.
ExternalHistorianAddPoint — adds a data point for this historian connection.
ExternalHistorianApplyEdit — applies edits made to the temporary copy of the configuration.
ExternalHistorianBeginEdit — creates a temporary copy of the configuration for editing.
ExternalHistorianCancelEdit — deletes the temporary configuration and all edits made to it.
ExternalHistorianEnable — enables or disables external historian connections.
ExternalHistorianGet — gets the value of a historian configuration option.
ExternalHistorianRemovePoint — removes a data point from a historian connection.
ExternalHistorianSet — sets the value of a historian configuration option.
force — forces a write to a point.
format — is an efficiency enhancement for Linux.
get_client_stats — provides statistics for all clients.
heartbeat — establishes a heartbeat message.
HistorianAdd — adds a point to a Historian group.
HistorianFlags — is new, not yet documented.
HistorianRemove — removes points.
HistorianSaveConfig — saves the configuration of the Historian.
HistorianSetConfiguring — sets the Historian status to "Configuring".
HistoryGroupAdd — adds a new history group.
HistoryGroupAddPoint — adds a point to a Historian group.
HistoryGroupDeadband — sets a deadband for a Historian group.
HistoryGroupDefault — sets a default group.
HistoryGroupFileTimes — sets a frequency for changing history files.
HistoryGroupFlushTimes — specifies how frequently to flush history data to disk.
HistoryGroupRemove — removes a group and all of its histories.
HistoryGroupStorageTimes — specifies how long to keep data in a history.
ignore — ignores a given point.
ignore_old_data — ignores changes with an old timestamp.
include — includes a file in with configuration files.
instance — creates an instance of a data organization model.
load_config_files — loads configuration files.
load_plugin — loads a specified plugin. (experimental)
load_scripts — loads scripts.
lock — locks and unlocks points.
log_file — sets up a log file.
log_file_max — sets a size limit for log files.
log_to_file — starts or stops logging to a file.
mirror_master — sets up a mirroring master.
mirror_master_2 — sets up a secure mirroring master.
ModbusApplySettings — applies all scripted changes.
ModbusCancelSettings — cancels all scripted changes.
ModbusCreateSlave — creates a slave connection.
ModbusDeleteSlave — deletes a slave connection.
ModbusEnableMaster — enables and disables Modbus master functionality.
ModbusEnableSlave — enables and disables Modbus slave connections.
ModbusQuerySlave — checks for the existence of a slave connection.
ModbusReloadSettings — loads all Modbus configuration.
ModbusSlaveAddPoint — configures a Modbus point.
ModbusSlaveAddRange — configures a range of Modbus points.
ModbusSlaveDeletePoint — deletes point connections.
mult — multiplies the value of a point.
OPCActivate — activates or deactivates an OPC group.
OPCAddItem2 — adds OPC items to a connection.
OPCAEAttach — creates an OPC A&E connection.
OPCAEDetach — deletes an OPC A&E connection.
OPCAEEnable — enables an OPC A&E connection.
OPCAEEnableClient — enables OPC A&E client behavior.
OPCAEEnableServer — enables OPC A&E server behavior.
OPCAEFilter — selects alarms and events by filtering criteria.
OPCAEServerInit — configures the OPC A&E server.
OPCApply — applies changes to an outgoing connection.
OPCAttach2 — sets up an OPC connection.
OPCConnect — connects or disconnects from the OPC server.
OPCDetach — removes an outgoing OPC connection.
OPCEnable — enables or disables outgoing OPC connections.
OPCEnableClient — enables or disables all OPC clients.
OPCEnableServer — enables or disables DataHub OPC server behavior.
OPCMinimumSecurity — overrides DCOM security settings.
OPCModify — modifies an existing OPC connection.
OPCQueryConnection — provides information related to an OPC server connection.
OPCQueryConnections — lists OPC server connections.
OPCQueryPoint — provides data about an OPC point.
OPCQueryPointPattern — provides data about multiple OPC points.
OPCQueryPoints — provides a list of explicitly configured OPC tags in a connection.
OPCRefresh — sends a Refresh2 command to the OPC server.
OPCReload — reloads the data set from an OPC server.
OPCRemoveItem — removes an item based on its DataHub point name.
private_attribute — creates a private attribute.
property — creates a property for an assembly.
quality — assigns a quality to a point.
read — reads a complete point definition.
report — requests notification of changes to a data point.
report_domain — registers points and requests information on a whole domain.
report_errors — controls the reporting of errors.
request_initial_data — gets current data when client connection is made.
save_config — forces a DataHub instance to save its configuration.
secure — adjusts the security level of a point.
set — sets the value of a point.
set_access — is new, not yet documented.
set_authoritative — sets the type of a point.
set_canonical — sets the type of a point.
show_data — displays the Data Browser.
show_debug_messages — show or hide debugging messages in the Data Browser.
show_event_log — displays the Event Log.
show_icon — displays the system tray icon.
show_properties — displays the Properties window.
show_script_log — displays the Script Log.
subassembly — creates a subassembly.
success — sets up a success message.
tcp_service — sets a TCP service name or port number for incoming slave connections.
timeout — suspends data flow.
transmit_insignificant — permits transmission of insignificant changes.
TunnelDelete — deletes specified tunnel/mirror Slave connections.
TunnelEnable — enables specified tunnel/mirror Slave connections.
TunnelEnablePlain — enables plain-text tunnel/mirror Master connections.
TunnelEnableSlave — enables all tunnel/mirror Slave connections.
TunnelEnableSSL — enables SSL tunnel/mirror Master connections.
TunnelPlainPort — specifies the port for incoming plain-text tunnels.
TunnelSaveConfig — saves the tunnel configuration.
TunnelSlaveStatus — provides status information on tunnel/mirror Slave connections.
TunnelSSLCert — specifies the certificate for incoming SSL-enabled tunnels.
TunnelSSLPort — specifies the port for incoming SSL-enabled tunnels.
type — creates a type.
UAApplyEdit — applies edits to OPC UA configuration.
UABeginEdit — creates a temporary copy of the OPC UA configuration for editing.
UACancelEdit — cancels edits to the OPC UA configuration.
UAEnable — enables or disables an individual OPC UA client connection.
UAEnableClient — enables or disables OPC UA client functionality.
UAEnableServer — enables or disables OPC UA server functionality.
unload_plugin — unloads a plugin. (experimental)
unreport — allows a client to stop receiving data value changes to a point.
unreport_domain — allows a client to stop receiving data value changes in a whole domain.
version — returns the current version number.
write — writes information to a point.
Obsolete and Unused Commands
asyncsocket — sets up asynchronous communication on a socket.
authgroup — is deprecated.
authuser — is deprecated.
bandwidth_reduce — is for internal use only.
deleted — checks if a point has been deleted.
drop_license — is for internal use only.
echo — is for internal use.
enable_connect_server — is deprecated.
EnableDDEServer — is for internal use only.
exception_buffer — is deprecated.
failed_license — is for internal use only.
flush — flushes output to a terminal (Linux).
flush_log — is deprecated.
master_host — is deprecated in favor of mirror_master.
master_service — is deprecated in favor of mirror_master.
on_change — is for internal use only.
OPCAddItem — is deprecated in favor of OPCAddItem2.
OPCAttach — is deprecated in favor of OPCAttach2.
OPCInit — is deprecated.
point — is used internally.
qnx_name_attach — does nothing.
qnx_receiver — does nothing.
readid — should not be used.
register_datahub — replaced by report_domain.
report_all — replaced by report_domain.
report_datahubs — does nothing.
request — replaced by report_domain.
run — does nothing.
script_register — is for internal use only.
script_symbol — is for internal use only.
slave — is for internal use only.
sync — is for internal use only.
taskdied — is for internal use.
taskstarted — is for internal use.
using_license — is for internal use only.
warn_of_license_expiry — is deprecated.
Appendices
1. Command Line Options
2. Excel Macro Library
2.1. Configure Excel to receive data from the DataHub instance (using DDEAdvise)
2.2. Write data from Excel - User initiated (using DDEPoke)
2.3. Write data from Excel - Automatically on value change (using DDEPoke)
2.4. Other Useful Macros
3. Running as a Windows Service (Specified User)
4. Windows Services File for Tunnel/Mirror
5. DataHub Registry Entries
6. OPC Overview
7. DDE Overview
8. ODBC Database Concepts
9. Error Messages
9.1. Windows Error Numbers
9.2. Windows TCP Error Numbers
9.3. Windows DDE Error Numbers
10. Third-Party Source Licenses
11. Media Source Licenses
12. GNU General Public License
13. GNU Lesser General Public License
List of Tables
3.1. Supported Modbus Read Functions
3.2. Supported Modbus Write Functions - Optional