diff --git a/src/.vuepress/public/img/opc-da-1-1.png b/src/.vuepress/public/img/opc-da-1-1.png new file mode 100644 index 000000000..632cc8c21 Binary files /dev/null and b/src/.vuepress/public/img/opc-da-1-1.png differ diff --git a/src/.vuepress/public/img/opc-da-1-2-en.png b/src/.vuepress/public/img/opc-da-1-2-en.png new file mode 100644 index 000000000..2acf40baa Binary files /dev/null and b/src/.vuepress/public/img/opc-da-1-2-en.png differ diff --git a/src/.vuepress/public/img/opc-da-1-2.png b/src/.vuepress/public/img/opc-da-1-2.png new file mode 100644 index 000000000..9fe6e3590 Binary files /dev/null and b/src/.vuepress/public/img/opc-da-1-2.png differ diff --git a/src/.vuepress/public/img/opc-da-2-1-en.png b/src/.vuepress/public/img/opc-da-2-1-en.png new file mode 100644 index 000000000..51f90593e Binary files /dev/null and b/src/.vuepress/public/img/opc-da-2-1-en.png differ diff --git a/src/.vuepress/public/img/opc-da-2-1.png b/src/.vuepress/public/img/opc-da-2-1.png new file mode 100644 index 000000000..afdc0d53f Binary files /dev/null and b/src/.vuepress/public/img/opc-da-2-1.png differ diff --git a/src/.vuepress/public/img/opc-da-3-1.png b/src/.vuepress/public/img/opc-da-3-1.png new file mode 100644 index 000000000..632cc8c21 Binary files /dev/null and b/src/.vuepress/public/img/opc-da-3-1.png differ diff --git a/src/.vuepress/public/img/opc-da-3-10-en.png b/src/.vuepress/public/img/opc-da-3-10-en.png new file mode 100644 index 000000000..42d71654a Binary files /dev/null and b/src/.vuepress/public/img/opc-da-3-10-en.png differ diff --git a/src/.vuepress/public/img/opc-da-3-10.png b/src/.vuepress/public/img/opc-da-3-10.png new file mode 100644 index 000000000..2d8c78067 Binary files /dev/null and b/src/.vuepress/public/img/opc-da-3-10.png differ diff --git a/src/.vuepress/public/img/opc-da-3-11.png b/src/.vuepress/public/img/opc-da-3-11.png new file mode 100644 index 000000000..d235ae2f4 Binary files /dev/null and b/src/.vuepress/public/img/opc-da-3-11.png differ diff --git a/src/.vuepress/public/img/opc-da-3-12-en.png b/src/.vuepress/public/img/opc-da-3-12-en.png new file mode 100644 index 000000000..a2339d714 Binary files /dev/null and b/src/.vuepress/public/img/opc-da-3-12-en.png differ diff --git a/src/.vuepress/public/img/opc-da-3-12.png b/src/.vuepress/public/img/opc-da-3-12.png new file mode 100644 index 000000000..e78b547d3 Binary files /dev/null and b/src/.vuepress/public/img/opc-da-3-12.png differ diff --git a/src/.vuepress/public/img/opc-da-3-13-en.png b/src/.vuepress/public/img/opc-da-3-13-en.png new file mode 100644 index 000000000..fe6bd14fd Binary files /dev/null and b/src/.vuepress/public/img/opc-da-3-13-en.png differ diff --git a/src/.vuepress/public/img/opc-da-3-13.png b/src/.vuepress/public/img/opc-da-3-13.png new file mode 100644 index 000000000..67cced24f Binary files /dev/null and b/src/.vuepress/public/img/opc-da-3-13.png differ diff --git a/src/.vuepress/public/img/opc-da-3-14-en.png b/src/.vuepress/public/img/opc-da-3-14-en.png new file mode 100644 index 000000000..816c13500 Binary files /dev/null and b/src/.vuepress/public/img/opc-da-3-14-en.png differ diff --git a/src/.vuepress/public/img/opc-da-3-14.png b/src/.vuepress/public/img/opc-da-3-14.png new file mode 100644 index 000000000..8ada3551d Binary files /dev/null and b/src/.vuepress/public/img/opc-da-3-14.png differ diff --git a/src/.vuepress/public/img/opc-da-3-15-en.png b/src/.vuepress/public/img/opc-da-3-15-en.png new file mode 100644 index 000000000..0f9c52fb1 Binary files /dev/null and b/src/.vuepress/public/img/opc-da-3-15-en.png differ diff --git a/src/.vuepress/public/img/opc-da-3-15.png b/src/.vuepress/public/img/opc-da-3-15.png new file mode 100644 index 000000000..dad0a53d6 Binary files /dev/null and b/src/.vuepress/public/img/opc-da-3-15.png differ diff --git a/src/.vuepress/public/img/opc-da-3-16-en.png b/src/.vuepress/public/img/opc-da-3-16-en.png new file mode 100644 index 000000000..a91993313 Binary files /dev/null and b/src/.vuepress/public/img/opc-da-3-16-en.png differ diff --git a/src/.vuepress/public/img/opc-da-3-16.png b/src/.vuepress/public/img/opc-da-3-16.png new file mode 100644 index 000000000..4ef38bafd Binary files /dev/null and b/src/.vuepress/public/img/opc-da-3-16.png differ diff --git a/src/.vuepress/public/img/opc-da-3-17-en.png b/src/.vuepress/public/img/opc-da-3-17-en.png new file mode 100644 index 000000000..ad5eae706 Binary files /dev/null and b/src/.vuepress/public/img/opc-da-3-17-en.png differ diff --git a/src/.vuepress/public/img/opc-da-3-17.png b/src/.vuepress/public/img/opc-da-3-17.png new file mode 100644 index 000000000..914814019 Binary files /dev/null and b/src/.vuepress/public/img/opc-da-3-17.png differ diff --git a/src/.vuepress/public/img/opc-da-3-18-en.png b/src/.vuepress/public/img/opc-da-3-18-en.png new file mode 100644 index 000000000..289bee760 Binary files /dev/null and b/src/.vuepress/public/img/opc-da-3-18-en.png differ diff --git a/src/.vuepress/public/img/opc-da-3-18.png b/src/.vuepress/public/img/opc-da-3-18.png new file mode 100644 index 000000000..f906c3d98 Binary files /dev/null and b/src/.vuepress/public/img/opc-da-3-18.png differ diff --git a/src/.vuepress/public/img/opc-da-3-2.png b/src/.vuepress/public/img/opc-da-3-2.png new file mode 100644 index 000000000..9b15e9899 Binary files /dev/null and b/src/.vuepress/public/img/opc-da-3-2.png differ diff --git a/src/.vuepress/public/img/opc-da-3-3-en.png b/src/.vuepress/public/img/opc-da-3-3-en.png new file mode 100644 index 000000000..a1c427b5c Binary files /dev/null and b/src/.vuepress/public/img/opc-da-3-3-en.png differ diff --git a/src/.vuepress/public/img/opc-da-3-3.png b/src/.vuepress/public/img/opc-da-3-3.png new file mode 100644 index 000000000..e72916a29 Binary files /dev/null and b/src/.vuepress/public/img/opc-da-3-3.png differ diff --git a/src/.vuepress/public/img/opc-da-3-4-en.png b/src/.vuepress/public/img/opc-da-3-4-en.png new file mode 100644 index 000000000..a6677d4ad Binary files /dev/null and b/src/.vuepress/public/img/opc-da-3-4-en.png differ diff --git a/src/.vuepress/public/img/opc-da-3-4.png b/src/.vuepress/public/img/opc-da-3-4.png new file mode 100644 index 000000000..42f9f2f9b Binary files /dev/null and b/src/.vuepress/public/img/opc-da-3-4.png differ diff --git a/src/.vuepress/public/img/opc-da-3-5-en.png b/src/.vuepress/public/img/opc-da-3-5-en.png new file mode 100644 index 000000000..88c43da77 Binary files /dev/null and b/src/.vuepress/public/img/opc-da-3-5-en.png differ diff --git a/src/.vuepress/public/img/opc-da-3-5.png b/src/.vuepress/public/img/opc-da-3-5.png new file mode 100644 index 000000000..3f2ac437b Binary files /dev/null and b/src/.vuepress/public/img/opc-da-3-5.png differ diff --git a/src/.vuepress/public/img/opc-da-3-6-en.png b/src/.vuepress/public/img/opc-da-3-6-en.png new file mode 100644 index 000000000..cb3b6d673 Binary files /dev/null and b/src/.vuepress/public/img/opc-da-3-6-en.png differ diff --git a/src/.vuepress/public/img/opc-da-3-6.png b/src/.vuepress/public/img/opc-da-3-6.png new file mode 100644 index 000000000..d0409499c Binary files /dev/null and b/src/.vuepress/public/img/opc-da-3-6.png differ diff --git a/src/.vuepress/public/img/opc-da-3-7-en.png b/src/.vuepress/public/img/opc-da-3-7-en.png new file mode 100644 index 000000000..7c9792daf Binary files /dev/null and b/src/.vuepress/public/img/opc-da-3-7-en.png differ diff --git a/src/.vuepress/public/img/opc-da-3-7.png b/src/.vuepress/public/img/opc-da-3-7.png new file mode 100644 index 000000000..6cb7d0e3c Binary files /dev/null and b/src/.vuepress/public/img/opc-da-3-7.png differ diff --git a/src/.vuepress/public/img/opc-da-3-8-en.png b/src/.vuepress/public/img/opc-da-3-8-en.png new file mode 100644 index 000000000..333cee80d Binary files /dev/null and b/src/.vuepress/public/img/opc-da-3-8-en.png differ diff --git a/src/.vuepress/public/img/opc-da-3-8.png b/src/.vuepress/public/img/opc-da-3-8.png new file mode 100644 index 000000000..51ded24ed Binary files /dev/null and b/src/.vuepress/public/img/opc-da-3-8.png differ diff --git a/src/.vuepress/public/img/opc-da-3-9.png b/src/.vuepress/public/img/opc-da-3-9.png new file mode 100644 index 000000000..1f23e140e Binary files /dev/null and b/src/.vuepress/public/img/opc-da-3-9.png differ diff --git a/src/.vuepress/sidebar_timecho/V1.3.x/en.ts b/src/.vuepress/sidebar_timecho/V1.3.x/en.ts index 3ea5da8a4..9fbdc84f0 100644 --- a/src/.vuepress/sidebar_timecho/V1.3.x/en.ts +++ b/src/.vuepress/sidebar_timecho/V1.3.x/en.ts @@ -200,6 +200,7 @@ export const enSidebar = { { text: 'JDBC', link: 'Programming-JDBC' }, { text: 'MQTT Protocol', link: 'Programming-MQTT' }, { text: 'OPC UA Protocol', link: 'Programming-OPC-UA_timecho' }, + { text: 'OPC DA Protocol', link: 'Programming-OPC-DA_timecho' }, { text: 'REST API', collapsible: true, diff --git a/src/.vuepress/sidebar_timecho/V1.3.x/zh.ts b/src/.vuepress/sidebar_timecho/V1.3.x/zh.ts index afeaf1a7e..d33c348ef 100644 --- a/src/.vuepress/sidebar_timecho/V1.3.x/zh.ts +++ b/src/.vuepress/sidebar_timecho/V1.3.x/zh.ts @@ -183,6 +183,7 @@ export const zhSidebar = { { text: 'JDBC', link: 'Programming-JDBC' }, { text: 'MQTT协议', link: 'Programming-MQTT' }, { text: 'OPC UA协议', link: 'Programming-OPC-UA_timecho' }, + { text: 'OPC DA协议', link: 'Programming-OPC-DA_timecho' }, { text: 'REST API', collapsible: true, diff --git a/src/.vuepress/sidebar_timecho/V2.0.x/en-Tree.ts b/src/.vuepress/sidebar_timecho/V2.0.x/en-Tree.ts index 4396e4b20..bf4eca8fd 100644 --- a/src/.vuepress/sidebar_timecho/V2.0.x/en-Tree.ts +++ b/src/.vuepress/sidebar_timecho/V2.0.x/en-Tree.ts @@ -195,6 +195,7 @@ export const enSidebar = { { text: 'JDBC', link: 'Programming-JDBC' }, { text: 'MQTT Protocol', link: 'Programming-MQTT' }, { text: 'OPC UA Protocol', link: 'Programming-OPC-UA_timecho' }, + { text: 'OPC DA Protocol', link: 'Programming-OPC-DA_timecho' }, { text: 'REST API', collapsible: true, diff --git a/src/.vuepress/sidebar_timecho/V2.0.x/zh-Tree.ts b/src/.vuepress/sidebar_timecho/V2.0.x/zh-Tree.ts index 9cf91c5c6..e3361b19c 100644 --- a/src/.vuepress/sidebar_timecho/V2.0.x/zh-Tree.ts +++ b/src/.vuepress/sidebar_timecho/V2.0.x/zh-Tree.ts @@ -178,6 +178,7 @@ export const zhSidebar = { { text: 'JDBC', link: 'Programming-JDBC' }, { text: 'MQTT协议', link: 'Programming-MQTT' }, { text: 'OPC UA协议', link: 'Programming-OPC-UA_timecho' }, + { text: 'OPC DA协议', link: 'Programming-OPC-DA_timecho' }, { text: 'REST API', collapsible: true, diff --git a/src/UserGuide/Master/Tree/API/Programming-OPC-DA_timecho.md b/src/UserGuide/Master/Tree/API/Programming-OPC-DA_timecho.md new file mode 100644 index 000000000..861d88e98 --- /dev/null +++ b/src/UserGuide/Master/Tree/API/Programming-OPC-DA_timecho.md @@ -0,0 +1,209 @@ + + +# OPC DA Protocol + +## 1. OPC DA + +OPC DA (OPC Data Access) is a communication protocol standard in the field of industrial automation and a core part of the classic OPC (OLE for Process Control) technology. Its primary goal is to enable real-time data exchange between industrial devices and software (such as SCADA, HMI, and databases) in a Windows environment. OPC DA is implemented based on COM/DCOM and is a lightweight protocol with two roles: server and client. + +* **Server:** Can be regarded as a pool of items, storing the latest data and status of each instance. All items can only be managed on the server side; clients can only read and write data and have no authority to manipulate metadata. + +![](/img/opc-da-1-1.png) + +* **Client:** After connecting to the server, the client needs to define a custom group (this group is only relevant to the client) and create items with the same names as those on the server. The client can then read and write the items it has created. + +![](/img/opc-da-1-2-en.png) + +## 2. OPC DA Sink + +IoTDB (available since V2.0.5.1 for V2.x) provides an OPC DA Sink that supports pushing tree-model data to a local COM server plugin. It encapsulates the OPC DA interface specifications and their inherent complexity, significantly simplifying the integration process. The data flow diagram for the OPC DA Sink is shown below. + +![](/img/opc-da-2-1-en.png) + +### 2.1 SQL Syntax + +```SQL +---- Note: The clsID here needs to be replaced with your own clsID +create pipe opc ( + 'sink'='opc-da-sink', + --- 'opcda.progid'='opcserversim.Instance.1' + 'opcda.clsid'='CAE8D0E1-117B-11D5-924B-11C0F023E91C' +); +``` + +### 2.2 Parameter Description + +| ​**​Parameter​**​ | ​**​Description​**​ | ​**​Value Range​**​ | ​**​Required​**​ | +| ----------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------- | ----------------------------------------- | +| sink | OPC DA Sink | String: opc-da-sink | Yes | +| sink.opcda.clsid | The ClsID (unique identifier string) of the OPC Server. It is recommended to use clsID instead of progID. | String | Either clsID or progID must be provided | +| sink.opcda.progid | The ProgID of the OPC Server. If clsID is available, it is preferred over progID. | String | Either clsID or progID must be provided | + + +### 2.3 Mapping Specifications + +When used, IoTDB will push the latest data from its tree model to the server. The itemID for the data is the full path of the time series in the tree model, such as root.a.b.c.d. Note that, according to the OPC DA standard, clients cannot directly create items on the server side. Therefore, the server must pre-create items corresponding to IoTDB's time series with the itemID and the appropriate data type. + +* Data type correspondence is as follows: + +| IoTDB | OPC-DA Server | +| ----------- | ----------------------------------------------------------- | +| INT32 | VT\_I4 | +| INT64 | VT\_I8 | +| FLOAT | VT\_R4 | +| DOUBLE | VT\_R8 | +| TEXT | VT\_BSTR | +| BOOLEAN | VT\_BOOL | +| DATE | VT\_DATE | +| TIMESTAMP | VT\_DATE | +| BLOB | VT_BSTR (Variant does not support VT_BLOB, so VT_BSTR is used as a substitute) | +| STRING | VT\_BSTR | + +### 2.4 Common Error Codes + +| Symbol | Error Code | Description | +| ----------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| OPC\_E\_BADTYPE | 0xC0040004 | The server cannot convert the data between the specified format/requested data type and the canonical data type. This means the server's data type does not match IoTDB's registered type. | +| OPC\_E\_UNKNOWNITEMID | 0xC0040007 | The item ID is not defined in the server's address space (when adding or validating), or the item ID no longer exists in the server's address space (when reading or writing). This means IoTDB's measurement point does not have a corresponding itemID on the server. | +| OPC\_E\_INVALIDITEMID | 0xC0040008 | The itemID does not conform to the server's syntax specifications. | +| REGDB\_E\_CLASSNOTREG | 0x80040154 | Class not registered | +| RPC\_S\_SERVER\_UNAVAILABLE | 0x800706BA | RPC service unavailable | +| DISP\_E\_OVERFLOW | 0x8002000A | Exceeds the maximum value of the type | +| DISP\_E\_BADVARTYPE | 0x80020005 | Type mismatch | + + +### 2.5 Usage Limitations + +* Only supports COM and can only be used on Windows. +* A small amount of old data may be pushed after restarting, but new data will eventually be pushed. +* Currently, only tree-model data is supported. + +## 3. Usage Steps +### 3.1 Prerequisites +1. Windows environment, version >= 8. +2. IoTDB is installed and running normally. +3. OPC DA Server is installed. + +* Using Simple OPC Server Simulator as an example: + +![](/img/opc-da-3-1.png) + +* Double-click an item to modify its name (itemID), data, data type, and other information. +* Right-click an item to delete it, update its value, or create a new item. + +![](/img/opc-da-3-2.png) + +4. OPC DA Client is installed. +* Using KepwareServerEX's quickClient as an example: +* In Kepware, the OPC DA Client can be opened as follows: + +![](/img/opc-da-3-3-en.png) + +![](/img/opc-da-3-4-en.png) + + +### 3.2 Configuration Modifications + +Modify the server configuration to prevent IoTDB's write client and Kepware's read client from connecting to two different instances, which would make debugging impossible. + +* First, press Win+R, type dcomcnfgin the Run menu, and open the DCOM component configuration: + +![](/img/opc-da-3-5-en.png) + +* Navigate to Component Services -> Computers -> My Computer -> DCOM Config, find AGG Software Simple OPC Server Simulator, right-click, and select "Properties": + +![](/img/opc-da-3-6-en.png) + +* Under Identity, change User Accountto Interactive User. Note: Do not use Launching User, as this may cause the two clients to start different server instances. + +![](/img/opc-da-3-7-en.png) + +### 3.3 Obtaining clsID +1. Method 1: Obtain via DCOM Configuration +* Press Win+R, type dcomcnfgin the Run menu, and open the DCOM component configuration. +* Navigate to Component Services -> Computers -> My Computer -> DCOM Config, find AGG Software Simple OPC Server Simulator, right-click, and select "Properties". +* Under General, you can obtain the application's clsID, which will be used for the opc-da-sink connection later. Note: Do not include the curly braces. + +![](/img/opc-da-3-8-en.png) + +2. Method 2: clsID and progID can also be obtained directly from the server. + +* Click `Help` > `Show OPC Server Info` + +![](/img/opc-da-3-9.png) + +* The pop-up window will display the information. + +![](/img/opc-da-3-10-en.png) + +### 3.4 Writing Data +#### 3.4.1 DA Server +1. Create a new item in the DA Server with the same name and type as the item to be written in IoTDB. + +![](/img/opc-da-3-11.png) + +2. Connect to the server in Kepware: + +![](/img/opc-da-3-12-en.png) + +3. Right-click the server to create a new group (the group name can be arbitrary): + +![](/img/opc-da-3-13-en.png) + +![](/img/opc-da-3-14-en.png) + +4. Right-click to create a new item with the same name as the one created earlier. + +![](/img/opc-da-3-15-en.png) + +![](/img/opc-da-3-16-en.png) + +![](/img/opc-da-3-17-en.png) + +#### 3.4.2 IoTDB + +1. Start IoTDB. +2. Create a Pipe. + +```SQL +create pipe opc ('sink'='opc-da-sink', 'opcda.clsid'='CAE8D0E1-117B-11D5-924B-11C0F023E91C') +``` + +* Note: If the creation fails with the error Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 1107: Failed to connect to server, error code: 0x80040154, refer to this solution: https://opcexpert.com/support/0x80040154-class-not-registered/. + +3. Create a time series (if automatic metadata creation is enabled, this step can be skipped). + +```SQL +create timeseries root.a.b.c.r string; +``` + +4. Insert data. + +```SQL +insert into root.a.b.c (time, r) values(10000, "SomeString") +``` + +### 3.5 Verifying Data + +Check the data in Quick Client; it should have been updated. + +![](/img/opc-da-3-18-en.png) \ No newline at end of file diff --git a/src/UserGuide/V1.3.x/API/Programming-OPC-DA_timecho.md b/src/UserGuide/V1.3.x/API/Programming-OPC-DA_timecho.md new file mode 100644 index 000000000..80e568300 --- /dev/null +++ b/src/UserGuide/V1.3.x/API/Programming-OPC-DA_timecho.md @@ -0,0 +1,209 @@ + + +# OPC DA Protocol + +## 1. OPC DA + +OPC DA (OPC Data Access) is a communication protocol standard in the field of industrial automation and a core part of the classic OPC (OLE for Process Control) technology. Its primary goal is to enable real-time data exchange between industrial devices and software (such as SCADA, HMI, and databases) in a Windows environment. OPC DA is implemented based on COM/DCOM and is a lightweight protocol with two roles: server and client. + +* **Server:** Can be regarded as a pool of items, storing the latest data and status of each instance. All items can only be managed on the server side; clients can only read and write data and have no authority to manipulate metadata. + +![](/img/opc-da-1-1.png) + +* **Client:** After connecting to the server, the client needs to define a custom group (this group is only relevant to the client) and create items with the same names as those on the server. The client can then read and write the items it has created. + +![](/img/opc-da-1-2-en.png) + +## 2. OPC DA Sink + +IoTDB (available since V1.3.5.2 for V1.x) provides an OPC DA Sink that supports pushing tree-model data to a local COM server plugin. It encapsulates the OPC DA interface specifications and their inherent complexity, significantly simplifying the integration process. The data flow diagram for the OPC DA Sink is shown below. + +![](/img/opc-da-2-1-en.png) + +### 2.1 SQL Syntax + +```SQL +---- Note: The clsID here needs to be replaced with your own clsID +create pipe opc ( + 'sink'='opc-da-sink', + --- 'opcda.progid'='opcserversim.Instance.1' + 'opcda.clsid'='CAE8D0E1-117B-11D5-924B-11C0F023E91C' +); +``` + +### 2.2 Parameter Description + +| ​**​Parameter​**​ | ​**​Description​**​ | ​**​Value Range​**​ | ​**​Required​**​ | +| ----------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------- | ----------------------------------------- | +| sink | OPC DA Sink | String: opc-da-sink | Yes | +| sink.opcda.clsid | The ClsID (unique identifier string) of the OPC Server. It is recommended to use clsID instead of progID. | String | Either clsID or progID must be provided | +| sink.opcda.progid | The ProgID of the OPC Server. If clsID is available, it is preferred over progID. | String | Either clsID or progID must be provided | + + +### 2.3 Mapping Specifications + +When used, IoTDB will push the latest data from its tree model to the server. The itemID for the data is the full path of the time series in the tree model, such as root.a.b.c.d. Note that, according to the OPC DA standard, clients cannot directly create items on the server side. Therefore, the server must pre-create items corresponding to IoTDB's time series with the itemID and the appropriate data type. + +* Data type correspondence is as follows: + +| IoTDB | OPC-DA Server | +| ----------- | ----------------------------------------------------------- | +| INT32 | VT\_I4 | +| INT64 | VT\_I8 | +| FLOAT | VT\_R4 | +| DOUBLE | VT\_R8 | +| TEXT | VT\_BSTR | +| BOOLEAN | VT\_BOOL | +| DATE | VT\_DATE | +| TIMESTAMP | VT\_DATE | +| BLOB | VT_BSTR (Variant does not support VT_BLOB, so VT_BSTR is used as a substitute) | +| STRING | VT\_BSTR | + +### 2.4 Common Error Codes + +| Symbol | Error Code | Description | +| ----------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| OPC\_E\_BADTYPE | 0xC0040004 | The server cannot convert the data between the specified format/requested data type and the canonical data type. This means the server's data type does not match IoTDB's registered type. | +| OPC\_E\_UNKNOWNITEMID | 0xC0040007 | The item ID is not defined in the server's address space (when adding or validating), or the item ID no longer exists in the server's address space (when reading or writing). This means IoTDB's measurement point does not have a corresponding itemID on the server. | +| OPC\_E\_INVALIDITEMID | 0xC0040008 | The itemID does not conform to the server's syntax specifications. | +| REGDB\_E\_CLASSNOTREG | 0x80040154 | Class not registered | +| RPC\_S\_SERVER\_UNAVAILABLE | 0x800706BA | RPC service unavailable | +| DISP\_E\_OVERFLOW | 0x8002000A | Exceeds the maximum value of the type | +| DISP\_E\_BADVARTYPE | 0x80020005 | Type mismatch | + + +### 2.5 Usage Limitations + +* Only supports COM and can only be used on Windows. +* A small amount of old data may be pushed after restarting, but new data will eventually be pushed. +* Currently, only tree-model data is supported. + +## 3. Usage Steps +### 3.1 Prerequisites +1. Windows environment, version >= 8. +2. IoTDB is installed and running normally. +3. OPC DA Server is installed. + +* Using Simple OPC Server Simulator as an example: + +![](/img/opc-da-3-1.png) + +* Double-click an item to modify its name (itemID), data, data type, and other information. +* Right-click an item to delete it, update its value, or create a new item. + +![](/img/opc-da-3-2.png) + +4. OPC DA Client is installed. +* Using KepwareServerEX's quickClient as an example: +* In Kepware, the OPC DA Client can be opened as follows: + +![](/img/opc-da-3-3-en.png) + +![](/img/opc-da-3-4-en.png) + + +### 3.2 Configuration Modifications + +Modify the server configuration to prevent IoTDB's write client and Kepware's read client from connecting to two different instances, which would make debugging impossible. + +* First, press Win+R, type dcomcnfgin the Run menu, and open the DCOM component configuration: + +![](/img/opc-da-3-5-en.png) + +* Navigate to Component Services -> Computers -> My Computer -> DCOM Config, find AGG Software Simple OPC Server Simulator, right-click, and select "Properties": + +![](/img/opc-da-3-6-en.png) + +* Under Identity, change User Accountto Interactive User. Note: Do not use Launching User, as this may cause the two clients to start different server instances. + +![](/img/opc-da-3-7-en.png) + +### 3.3 Obtaining clsID +1. Method 1: Obtain via DCOM Configuration +* Press Win+R, type dcomcnfgin the Run menu, and open the DCOM component configuration. +* Navigate to Component Services -> Computers -> My Computer -> DCOM Config, find AGG Software Simple OPC Server Simulator, right-click, and select "Properties". +* Under General, you can obtain the application's clsID, which will be used for the opc-da-sink connection later. Note: Do not include the curly braces. + +![](/img/opc-da-3-8-en.png) + +2. Method 2: clsID and progID can also be obtained directly from the server. + +* Click `Help` > `Show OPC Server Info` + +![](/img/opc-da-3-9.png) + +* The pop-up window will display the information. + +![](/img/opc-da-3-10-en.png) + +### 3.4 Writing Data +#### 3.4.1 DA Server +1. Create a new item in the DA Server with the same name and type as the item to be written in IoTDB. + +![](/img/opc-da-3-11.png) + +2. Connect to the server in Kepware: + +![](/img/opc-da-3-12-en.png) + +3. Right-click the server to create a new group (the group name can be arbitrary): + +![](/img/opc-da-3-13-en.png) + +![](/img/opc-da-3-14-en.png) + +4. Right-click to create a new item with the same name as the one created earlier. + +![](/img/opc-da-3-15-en.png) + +![](/img/opc-da-3-16-en.png) + +![](/img/opc-da-3-17-en.png) + +#### 3.4.2 IoTDB + +1. Start IoTDB. +2. Create a Pipe. + +```SQL +create pipe opc ('sink'='opc-da-sink', 'opcda.clsid'='CAE8D0E1-117B-11D5-924B-11C0F023E91C') +``` + +* Note: If the creation fails with the error Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 1107: Failed to connect to server, error code: 0x80040154, refer to this solution: https://opcexpert.com/support/0x80040154-class-not-registered/. + +3. Create a time series (if automatic metadata creation is enabled, this step can be skipped). + +```SQL +create timeseries root.a.b.c.r string; +``` + +4. Insert data. + +```SQL +insert into root.a.b.c (time, r) values(10000, "SomeString") +``` + +### 3.5 Verifying Data + +Check the data in Quick Client; it should have been updated. + +![](/img/opc-da-3-18-en.png) \ No newline at end of file diff --git a/src/UserGuide/dev-1.3/API/Programming-OPC-DA_timecho.md b/src/UserGuide/dev-1.3/API/Programming-OPC-DA_timecho.md new file mode 100644 index 000000000..80e568300 --- /dev/null +++ b/src/UserGuide/dev-1.3/API/Programming-OPC-DA_timecho.md @@ -0,0 +1,209 @@ + + +# OPC DA Protocol + +## 1. OPC DA + +OPC DA (OPC Data Access) is a communication protocol standard in the field of industrial automation and a core part of the classic OPC (OLE for Process Control) technology. Its primary goal is to enable real-time data exchange between industrial devices and software (such as SCADA, HMI, and databases) in a Windows environment. OPC DA is implemented based on COM/DCOM and is a lightweight protocol with two roles: server and client. + +* **Server:** Can be regarded as a pool of items, storing the latest data and status of each instance. All items can only be managed on the server side; clients can only read and write data and have no authority to manipulate metadata. + +![](/img/opc-da-1-1.png) + +* **Client:** After connecting to the server, the client needs to define a custom group (this group is only relevant to the client) and create items with the same names as those on the server. The client can then read and write the items it has created. + +![](/img/opc-da-1-2-en.png) + +## 2. OPC DA Sink + +IoTDB (available since V1.3.5.2 for V1.x) provides an OPC DA Sink that supports pushing tree-model data to a local COM server plugin. It encapsulates the OPC DA interface specifications and their inherent complexity, significantly simplifying the integration process. The data flow diagram for the OPC DA Sink is shown below. + +![](/img/opc-da-2-1-en.png) + +### 2.1 SQL Syntax + +```SQL +---- Note: The clsID here needs to be replaced with your own clsID +create pipe opc ( + 'sink'='opc-da-sink', + --- 'opcda.progid'='opcserversim.Instance.1' + 'opcda.clsid'='CAE8D0E1-117B-11D5-924B-11C0F023E91C' +); +``` + +### 2.2 Parameter Description + +| ​**​Parameter​**​ | ​**​Description​**​ | ​**​Value Range​**​ | ​**​Required​**​ | +| ----------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------- | ----------------------------------------- | +| sink | OPC DA Sink | String: opc-da-sink | Yes | +| sink.opcda.clsid | The ClsID (unique identifier string) of the OPC Server. It is recommended to use clsID instead of progID. | String | Either clsID or progID must be provided | +| sink.opcda.progid | The ProgID of the OPC Server. If clsID is available, it is preferred over progID. | String | Either clsID or progID must be provided | + + +### 2.3 Mapping Specifications + +When used, IoTDB will push the latest data from its tree model to the server. The itemID for the data is the full path of the time series in the tree model, such as root.a.b.c.d. Note that, according to the OPC DA standard, clients cannot directly create items on the server side. Therefore, the server must pre-create items corresponding to IoTDB's time series with the itemID and the appropriate data type. + +* Data type correspondence is as follows: + +| IoTDB | OPC-DA Server | +| ----------- | ----------------------------------------------------------- | +| INT32 | VT\_I4 | +| INT64 | VT\_I8 | +| FLOAT | VT\_R4 | +| DOUBLE | VT\_R8 | +| TEXT | VT\_BSTR | +| BOOLEAN | VT\_BOOL | +| DATE | VT\_DATE | +| TIMESTAMP | VT\_DATE | +| BLOB | VT_BSTR (Variant does not support VT_BLOB, so VT_BSTR is used as a substitute) | +| STRING | VT\_BSTR | + +### 2.4 Common Error Codes + +| Symbol | Error Code | Description | +| ----------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| OPC\_E\_BADTYPE | 0xC0040004 | The server cannot convert the data between the specified format/requested data type and the canonical data type. This means the server's data type does not match IoTDB's registered type. | +| OPC\_E\_UNKNOWNITEMID | 0xC0040007 | The item ID is not defined in the server's address space (when adding or validating), or the item ID no longer exists in the server's address space (when reading or writing). This means IoTDB's measurement point does not have a corresponding itemID on the server. | +| OPC\_E\_INVALIDITEMID | 0xC0040008 | The itemID does not conform to the server's syntax specifications. | +| REGDB\_E\_CLASSNOTREG | 0x80040154 | Class not registered | +| RPC\_S\_SERVER\_UNAVAILABLE | 0x800706BA | RPC service unavailable | +| DISP\_E\_OVERFLOW | 0x8002000A | Exceeds the maximum value of the type | +| DISP\_E\_BADVARTYPE | 0x80020005 | Type mismatch | + + +### 2.5 Usage Limitations + +* Only supports COM and can only be used on Windows. +* A small amount of old data may be pushed after restarting, but new data will eventually be pushed. +* Currently, only tree-model data is supported. + +## 3. Usage Steps +### 3.1 Prerequisites +1. Windows environment, version >= 8. +2. IoTDB is installed and running normally. +3. OPC DA Server is installed. + +* Using Simple OPC Server Simulator as an example: + +![](/img/opc-da-3-1.png) + +* Double-click an item to modify its name (itemID), data, data type, and other information. +* Right-click an item to delete it, update its value, or create a new item. + +![](/img/opc-da-3-2.png) + +4. OPC DA Client is installed. +* Using KepwareServerEX's quickClient as an example: +* In Kepware, the OPC DA Client can be opened as follows: + +![](/img/opc-da-3-3-en.png) + +![](/img/opc-da-3-4-en.png) + + +### 3.2 Configuration Modifications + +Modify the server configuration to prevent IoTDB's write client and Kepware's read client from connecting to two different instances, which would make debugging impossible. + +* First, press Win+R, type dcomcnfgin the Run menu, and open the DCOM component configuration: + +![](/img/opc-da-3-5-en.png) + +* Navigate to Component Services -> Computers -> My Computer -> DCOM Config, find AGG Software Simple OPC Server Simulator, right-click, and select "Properties": + +![](/img/opc-da-3-6-en.png) + +* Under Identity, change User Accountto Interactive User. Note: Do not use Launching User, as this may cause the two clients to start different server instances. + +![](/img/opc-da-3-7-en.png) + +### 3.3 Obtaining clsID +1. Method 1: Obtain via DCOM Configuration +* Press Win+R, type dcomcnfgin the Run menu, and open the DCOM component configuration. +* Navigate to Component Services -> Computers -> My Computer -> DCOM Config, find AGG Software Simple OPC Server Simulator, right-click, and select "Properties". +* Under General, you can obtain the application's clsID, which will be used for the opc-da-sink connection later. Note: Do not include the curly braces. + +![](/img/opc-da-3-8-en.png) + +2. Method 2: clsID and progID can also be obtained directly from the server. + +* Click `Help` > `Show OPC Server Info` + +![](/img/opc-da-3-9.png) + +* The pop-up window will display the information. + +![](/img/opc-da-3-10-en.png) + +### 3.4 Writing Data +#### 3.4.1 DA Server +1. Create a new item in the DA Server with the same name and type as the item to be written in IoTDB. + +![](/img/opc-da-3-11.png) + +2. Connect to the server in Kepware: + +![](/img/opc-da-3-12-en.png) + +3. Right-click the server to create a new group (the group name can be arbitrary): + +![](/img/opc-da-3-13-en.png) + +![](/img/opc-da-3-14-en.png) + +4. Right-click to create a new item with the same name as the one created earlier. + +![](/img/opc-da-3-15-en.png) + +![](/img/opc-da-3-16-en.png) + +![](/img/opc-da-3-17-en.png) + +#### 3.4.2 IoTDB + +1. Start IoTDB. +2. Create a Pipe. + +```SQL +create pipe opc ('sink'='opc-da-sink', 'opcda.clsid'='CAE8D0E1-117B-11D5-924B-11C0F023E91C') +``` + +* Note: If the creation fails with the error Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 1107: Failed to connect to server, error code: 0x80040154, refer to this solution: https://opcexpert.com/support/0x80040154-class-not-registered/. + +3. Create a time series (if automatic metadata creation is enabled, this step can be skipped). + +```SQL +create timeseries root.a.b.c.r string; +``` + +4. Insert data. + +```SQL +insert into root.a.b.c (time, r) values(10000, "SomeString") +``` + +### 3.5 Verifying Data + +Check the data in Quick Client; it should have been updated. + +![](/img/opc-da-3-18-en.png) \ No newline at end of file diff --git a/src/UserGuide/latest/API/Programming-OPC-DA_timecho.md b/src/UserGuide/latest/API/Programming-OPC-DA_timecho.md new file mode 100644 index 000000000..861d88e98 --- /dev/null +++ b/src/UserGuide/latest/API/Programming-OPC-DA_timecho.md @@ -0,0 +1,209 @@ + + +# OPC DA Protocol + +## 1. OPC DA + +OPC DA (OPC Data Access) is a communication protocol standard in the field of industrial automation and a core part of the classic OPC (OLE for Process Control) technology. Its primary goal is to enable real-time data exchange between industrial devices and software (such as SCADA, HMI, and databases) in a Windows environment. OPC DA is implemented based on COM/DCOM and is a lightweight protocol with two roles: server and client. + +* **Server:** Can be regarded as a pool of items, storing the latest data and status of each instance. All items can only be managed on the server side; clients can only read and write data and have no authority to manipulate metadata. + +![](/img/opc-da-1-1.png) + +* **Client:** After connecting to the server, the client needs to define a custom group (this group is only relevant to the client) and create items with the same names as those on the server. The client can then read and write the items it has created. + +![](/img/opc-da-1-2-en.png) + +## 2. OPC DA Sink + +IoTDB (available since V2.0.5.1 for V2.x) provides an OPC DA Sink that supports pushing tree-model data to a local COM server plugin. It encapsulates the OPC DA interface specifications and their inherent complexity, significantly simplifying the integration process. The data flow diagram for the OPC DA Sink is shown below. + +![](/img/opc-da-2-1-en.png) + +### 2.1 SQL Syntax + +```SQL +---- Note: The clsID here needs to be replaced with your own clsID +create pipe opc ( + 'sink'='opc-da-sink', + --- 'opcda.progid'='opcserversim.Instance.1' + 'opcda.clsid'='CAE8D0E1-117B-11D5-924B-11C0F023E91C' +); +``` + +### 2.2 Parameter Description + +| ​**​Parameter​**​ | ​**​Description​**​ | ​**​Value Range​**​ | ​**​Required​**​ | +| ----------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------- | ----------------------------------------- | +| sink | OPC DA Sink | String: opc-da-sink | Yes | +| sink.opcda.clsid | The ClsID (unique identifier string) of the OPC Server. It is recommended to use clsID instead of progID. | String | Either clsID or progID must be provided | +| sink.opcda.progid | The ProgID of the OPC Server. If clsID is available, it is preferred over progID. | String | Either clsID or progID must be provided | + + +### 2.3 Mapping Specifications + +When used, IoTDB will push the latest data from its tree model to the server. The itemID for the data is the full path of the time series in the tree model, such as root.a.b.c.d. Note that, according to the OPC DA standard, clients cannot directly create items on the server side. Therefore, the server must pre-create items corresponding to IoTDB's time series with the itemID and the appropriate data type. + +* Data type correspondence is as follows: + +| IoTDB | OPC-DA Server | +| ----------- | ----------------------------------------------------------- | +| INT32 | VT\_I4 | +| INT64 | VT\_I8 | +| FLOAT | VT\_R4 | +| DOUBLE | VT\_R8 | +| TEXT | VT\_BSTR | +| BOOLEAN | VT\_BOOL | +| DATE | VT\_DATE | +| TIMESTAMP | VT\_DATE | +| BLOB | VT_BSTR (Variant does not support VT_BLOB, so VT_BSTR is used as a substitute) | +| STRING | VT\_BSTR | + +### 2.4 Common Error Codes + +| Symbol | Error Code | Description | +| ----------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| OPC\_E\_BADTYPE | 0xC0040004 | The server cannot convert the data between the specified format/requested data type and the canonical data type. This means the server's data type does not match IoTDB's registered type. | +| OPC\_E\_UNKNOWNITEMID | 0xC0040007 | The item ID is not defined in the server's address space (when adding or validating), or the item ID no longer exists in the server's address space (when reading or writing). This means IoTDB's measurement point does not have a corresponding itemID on the server. | +| OPC\_E\_INVALIDITEMID | 0xC0040008 | The itemID does not conform to the server's syntax specifications. | +| REGDB\_E\_CLASSNOTREG | 0x80040154 | Class not registered | +| RPC\_S\_SERVER\_UNAVAILABLE | 0x800706BA | RPC service unavailable | +| DISP\_E\_OVERFLOW | 0x8002000A | Exceeds the maximum value of the type | +| DISP\_E\_BADVARTYPE | 0x80020005 | Type mismatch | + + +### 2.5 Usage Limitations + +* Only supports COM and can only be used on Windows. +* A small amount of old data may be pushed after restarting, but new data will eventually be pushed. +* Currently, only tree-model data is supported. + +## 3. Usage Steps +### 3.1 Prerequisites +1. Windows environment, version >= 8. +2. IoTDB is installed and running normally. +3. OPC DA Server is installed. + +* Using Simple OPC Server Simulator as an example: + +![](/img/opc-da-3-1.png) + +* Double-click an item to modify its name (itemID), data, data type, and other information. +* Right-click an item to delete it, update its value, or create a new item. + +![](/img/opc-da-3-2.png) + +4. OPC DA Client is installed. +* Using KepwareServerEX's quickClient as an example: +* In Kepware, the OPC DA Client can be opened as follows: + +![](/img/opc-da-3-3-en.png) + +![](/img/opc-da-3-4-en.png) + + +### 3.2 Configuration Modifications + +Modify the server configuration to prevent IoTDB's write client and Kepware's read client from connecting to two different instances, which would make debugging impossible. + +* First, press Win+R, type dcomcnfgin the Run menu, and open the DCOM component configuration: + +![](/img/opc-da-3-5-en.png) + +* Navigate to Component Services -> Computers -> My Computer -> DCOM Config, find AGG Software Simple OPC Server Simulator, right-click, and select "Properties": + +![](/img/opc-da-3-6-en.png) + +* Under Identity, change User Accountto Interactive User. Note: Do not use Launching User, as this may cause the two clients to start different server instances. + +![](/img/opc-da-3-7-en.png) + +### 3.3 Obtaining clsID +1. Method 1: Obtain via DCOM Configuration +* Press Win+R, type dcomcnfgin the Run menu, and open the DCOM component configuration. +* Navigate to Component Services -> Computers -> My Computer -> DCOM Config, find AGG Software Simple OPC Server Simulator, right-click, and select "Properties". +* Under General, you can obtain the application's clsID, which will be used for the opc-da-sink connection later. Note: Do not include the curly braces. + +![](/img/opc-da-3-8-en.png) + +2. Method 2: clsID and progID can also be obtained directly from the server. + +* Click `Help` > `Show OPC Server Info` + +![](/img/opc-da-3-9.png) + +* The pop-up window will display the information. + +![](/img/opc-da-3-10-en.png) + +### 3.4 Writing Data +#### 3.4.1 DA Server +1. Create a new item in the DA Server with the same name and type as the item to be written in IoTDB. + +![](/img/opc-da-3-11.png) + +2. Connect to the server in Kepware: + +![](/img/opc-da-3-12-en.png) + +3. Right-click the server to create a new group (the group name can be arbitrary): + +![](/img/opc-da-3-13-en.png) + +![](/img/opc-da-3-14-en.png) + +4. Right-click to create a new item with the same name as the one created earlier. + +![](/img/opc-da-3-15-en.png) + +![](/img/opc-da-3-16-en.png) + +![](/img/opc-da-3-17-en.png) + +#### 3.4.2 IoTDB + +1. Start IoTDB. +2. Create a Pipe. + +```SQL +create pipe opc ('sink'='opc-da-sink', 'opcda.clsid'='CAE8D0E1-117B-11D5-924B-11C0F023E91C') +``` + +* Note: If the creation fails with the error Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 1107: Failed to connect to server, error code: 0x80040154, refer to this solution: https://opcexpert.com/support/0x80040154-class-not-registered/. + +3. Create a time series (if automatic metadata creation is enabled, this step can be skipped). + +```SQL +create timeseries root.a.b.c.r string; +``` + +4. Insert data. + +```SQL +insert into root.a.b.c (time, r) values(10000, "SomeString") +``` + +### 3.5 Verifying Data + +Check the data in Quick Client; it should have been updated. + +![](/img/opc-da-3-18-en.png) \ No newline at end of file diff --git a/src/zh/UserGuide/Master/Tree/API/Programming-OPC-DA_timecho.md b/src/zh/UserGuide/Master/Tree/API/Programming-OPC-DA_timecho.md new file mode 100644 index 000000000..f6dc7368d --- /dev/null +++ b/src/zh/UserGuide/Master/Tree/API/Programming-OPC-DA_timecho.md @@ -0,0 +1,208 @@ + + +# OPC DA 协议 + +## 1. OPC DA + +OPC DA (OPC Data Access) 是工业自动化领域的一种通信协议标准，属于经典 OPC（OLE for Process Control）技术的核心部分。它的主要目标是实现 Windows 环境下工业设备与软件（如 SCADA、HMI、数据库）之间的实时数据交互。OPC DA 基于 COM / DCOM 实现，是一个轻量级的协议，分为服务器和客户端两个角色。 + +* **服务器：** 可以视为一个 Item 的池，存储各个实例的最新数据及其状态。所有 item 只能在服务器端管理，客户端只能读写数据，无权操作元信息。 + +![](/img/opc-da-1-1.png) + +* **客户端：** 连接服务器后，需要自定义一个组（这个组仅与客户端有关），并创建服务器的同名 item，然后可以对自身已创建的 item 进行读写。 + +![](/img/opc-da-1-2.png) + +## 2. OPC DA Sink + +IoTDB （V2.0.5.1及以后的V2.x版本支持） 提供的 OPC DA Sink 支持将树模型数据推送到本地 COM 服务器的插件，它封装了 OPC DA 接口规范及其固有复杂性，显著简化了集成流程。OPC DA Sink 推送数据流图如下所示。 + +![](/img/opc-da-2-1.png) + +### 2.1 SQL 语法 + +```SQL +---- 注意这里的 clsID 需要替换为自己的 clsID +create pipe opc ( + 'sink'='opc-da-sink', + --- 'opcda.progid'='opcserversim.Instance.1' + 'opcda.clsid'='CAE8D0E1-117B-11D5-924B-11C0F023E91C' +); +``` + +### 2.2 参数介绍 + +| **参数** | **描述** | **取值范围 ** | 是否必填 | +| ------------------- | --------------------------------------------------------------------- | ----------------------- | ------------------ | +| sink | OPC DA SINK | String: opc-da-sink | 必填 | +| sink.opcda.clsid | OPC Server 的 ClsID（唯一标识字符串）。建议使用 clsID 而非 progID。 | String | 和 progId 二选一 | +| sink.opcda.progid | OPC Server 的 ProgID，如果有 clsID，优先使用 clsID。 | String | 和 clsID 二选一 | + +### 2.3 映射规范 + +使用时，IoTDB 将会将自身的树模型最新数据推送到服务器，数据的 itemID 为树模型下的时间序列的全路径，如 `root.a.b.c.d`。注意根据 OPC DA 标准，客户端无权直接在 server 侧创建 item，因此需要服务器提前将 IoTDB 的时间序列以 itemID 和对应数据类型的格式创建为 item。 + +* 数据类型对应如下表所示。 + +| IoTDB | OPC-DA Server | +| ----------- | ----------------------------------------------------------- | +| INT32 | VT\_I4 | +| INT64 | VT\_I8 | +| FLOAT | VT\_R4 | +| DOUBLE | VT\_R8 | +| TEXT | VT\_BSTR | +| BOOLEAN | VT\_BOOL | +| DATE | VT\_DATE | +| TIMESTAMP | VT\_DATE | +| BLOB | VT\_BSTR（Variant 不支持 VT\_BLOB，因此用 VT\_BSTR 替代） | +| STRING | VT\_BSTR | + +### 2.4 常见错误码 + +| 符号 | 错误码 | 描述 | +| ----------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| OPC\_E\_BADTYPE | 0xC0040004 | 服务器无法在指定格式/请求的数据类型与规范数据类型之间转换数据。即服务器的数据类型与 IoTDB 的注册类型不一致。 | +| OPC\_E\_UNKNOWNITEMID| 0xC0040007 | 在服务器地址空间中未定义该条目ID（添加或验证时），或该条目ID在服务器地址空间中已不存在（读取或写入时）。即 IoTDB 的测点在服务器内没有对应的 itemID。 | +| OPC\_E\_INVALIDITEMID | 0xC0040008 | 该 itemID不符合服务器的语法规范。 | +| REGDB\_E\_CLASSNOTREG | 0x80040154 | 未注册类 | +| RPC\_S\_SERVER\_UNAVAILABLE | 0x800706ba | RPC服务不可用 | +| DISP\_E\_OVERFLOW | 0x8002000a | 超过类型的最大值 | +| DISP\_E\_BADVARTYPE | 0x80020005 | 类型不匹配 | + +### 2.5 使用限制 + +* 仅支持 COM，且仅能在 Windows 上使用 +* 重启后可能会推送少部分旧数据，但是最终会推送新数据 +* 目前仅支持树模型数据。 + +## 3. 使用步骤 +### 3.1 前置条件 +1. Windows 环境，版本 >= 8 +2. IoTDB 已安装且可正常运行 +3. OPC DA Server 已安装 + +* 以 Simple OPC Server Simulator 为例 + +![](/img/opc-da-3-1.png) + +* 双击某项，可以修改该项的名字（itemID），数据，数据类型等各个信息。 +* 右键某项，可以删除该项、更新值、以及新建项。 + +![](/img/opc-da-3-2.png) + +4. OPC DA Client 已安装 + +* 以 KepwareServerEX 的 quickClient 为例 +* 在 Kepware 中可以如下打开 OPC DA Client + +![](/img/opc-da-3-3.png) + +![](/img/opc-da-3-4.png) + + +### 3.2 配置修改 + +修改 server 配置，以避免 IoTDB 的写入 client 与 Kepware 的读取 client 连接到两个不同的实例而无法调试。 + +* 首先按 Win+R 键，在运行菜单内输入 `dcomcnfg`，打开 dcom 的组件配置： + +![](/img/opc-da-3-5.png) + +* 点击组件服务 -> 计算机 -> 我的电脑 -> DCOM 配置，找到`AGG Software Simple OPC Server Simulator`，右键“属性”： + +![](/img/opc-da-3-6.png) + +* 在`标识`内，将`用户账户`改为`交互式用户`。注意这里不要为`启动用户`，否则可能导致两个 client 分别启动不同的 server 实例。 + +![](/img/opc-da-3-7.png) + +### 3.3 clsID 获取 +1. 方式一：通过 DCOM 配置 获取 + +* 按 Win+R 键，在运行菜单内输入 `dcomcnfg`，打开 dcom 的组件配置； +* 点击组件服务 -> 计算机 -> 我的电脑 -> DCOM 配置，找到`AGG Software Simple OPC Server Simulator`，右键“属性”。 +* 在 `常规 `中可以获取该应用程序的 clsID，用于之后 opc-da-sink 的连接，注意不带大括号 + +![](/img/opc-da-3-8.png) + +2. 方式二：clsID 与 progID 也可以直接在 server 里获取 + +* 点击 `Help` > `Show OPC Server Info` + +![](/img/opc-da-3-9.png) + +* 弹窗中即可显示 + +![](/img/opc-da-3-10.png) + +### 3.4 写入数据 +#### 3.4.1 DA Server +1. 在 DA Server 内新建项，与 IoTDB 的待写入项的 name 与 type 保持一致 + +![](/img/opc-da-3-11.png) + +2. 在 Kepware 中连上该 server： + +![](/img/opc-da-3-12.png) + +3. 右键服务器新建组，组名任意： + +![](/img/opc-da-3-13.png) + +![](/img/opc-da-3-14.png) + +4. 右键新建 item，item 的名字为之前创建的名字 + +![](/img/opc-da-3-15.png) + +![](/img/opc-da-3-16.png) + +![](/img/opc-da-3-17.png) + +#### 3.4.2 IoTDB +1. 启动 IoTDB +2. 创建 Pipe + +```SQL +create pipe opc ('sink'='opc-da-sink', 'opcda.clsid'='CAE8D0E1-117B-11D5-924B-11C0F023E91C') +``` + +* 注意：如果创建失败，提示` Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 1107: Failed to connect to server, error code: 0x80040154`，则可以参考该解决方案进行处理：https://opcexpert.com/support/0x80040154-class-not-registered/ + +3. 创建时间序列（如果已开启自动创建元数据，则本步骤可以省略） + +```SQL +create timeseries root.a.b.c.r string; +``` + +4. 插入数据 + +```SQL +insert into root.a.b.c (time, r) values(10000, "SomeString") +``` + +### 3.5 验证数据 + +查看 Quick client 的数据，应该已经得到更新。 + +![](/img/opc-da-3-18.png) \ No newline at end of file diff --git a/src/zh/UserGuide/V1.3.x/API/Programming-OPC-DA_timecho.md b/src/zh/UserGuide/V1.3.x/API/Programming-OPC-DA_timecho.md new file mode 100644 index 000000000..435f28c80 --- /dev/null +++ b/src/zh/UserGuide/V1.3.x/API/Programming-OPC-DA_timecho.md @@ -0,0 +1,208 @@ + + +# OPC DA 协议 + +## 1. OPC DA + +OPC DA (OPC Data Access) 是工业自动化领域的一种通信协议标准，属于经典 OPC（OLE for Process Control）技术的核心部分。它的主要目标是实现 Windows 环境下工业设备与软件（如 SCADA、HMI、数据库）之间的实时数据交互。OPC DA 基于 COM / DCOM 实现，是一个轻量级的协议，分为服务器和客户端两个角色。 + +* **服务器：** 可以视为一个 Item 的池，存储各个实例的最新数据及其状态。所有 item 只能在服务器端管理，客户端只能读写数据，无权操作元信息。 + +![](/img/opc-da-1-1.png) + +* **客户端：** 连接服务器后，需要自定义一个组（这个组仅与客户端有关），并创建服务器的同名 item，然后可以对自身已创建的 item 进行读写。 + +![](/img/opc-da-1-2.png) + +## 2. OPC DA Sink + +IoTDB （V1.3.5.2及以后的V1.x版本支持） 提供的 OPC DA Sink 支持将树模型数据推送到本地 COM 服务器的插件，它封装了 OPC DA 接口规范及其固有复杂性，显著简化了集成流程。OPC DA Sink 推送数据流图如下所示。 + +![](/img/opc-da-2-1.png) + +### 2.1 SQL 语法 + +```SQL +---- 注意这里的 clsID 需要替换为自己的 clsID +create pipe opc ( + 'sink'='opc-da-sink', + --- 'opcda.progid'='opcserversim.Instance.1' + 'opcda.clsid'='CAE8D0E1-117B-11D5-924B-11C0F023E91C' +); +``` + +### 2.2 参数介绍 + +| **参数** | **描述** | **取值范围 ** | 是否必填 | +| ------------------- | --------------------------------------------------------------------- | ----------------------- | ------------------ | +| sink | OPC DA SINK | String: opc-da-sink | 必填 | +| sink.opcda.clsid | OPC Server 的 ClsID（唯一标识字符串）。建议使用 clsID 而非 progID。 | String | 和 progId 二选一 | +| sink.opcda.progid | OPC Server 的 ProgID，如果有 clsID，优先使用 clsID。 | String | 和 clsID 二选一 | + +### 2.3 映射规范 + +使用时，IoTDB 将会将自身的树模型最新数据推送到服务器，数据的 itemID 为树模型下的时间序列的全路径，如 `root.a.b.c.d`。注意根据 OPC DA 标准，客户端无权直接在 server 侧创建 item，因此需要服务器提前将 IoTDB 的时间序列以 itemID 和对应数据类型的格式创建为 item。 + +* 数据类型对应如下表所示。 + +| IoTDB | OPC-DA Server | +| ----------- | ----------------------------------------------------------- | +| INT32 | VT\_I4 | +| INT64 | VT\_I8 | +| FLOAT | VT\_R4 | +| DOUBLE | VT\_R8 | +| TEXT | VT\_BSTR | +| BOOLEAN | VT\_BOOL | +| DATE | VT\_DATE | +| TIMESTAMP | VT\_DATE | +| BLOB | VT\_BSTR（Variant 不支持 VT\_BLOB，因此用 VT\_BSTR 替代） | +| STRING | VT\_BSTR | + +### 2.4 常见错误码 + +| 符号 | 错误码 | 描述 | +| ----------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| OPC\_E\_BADTYPE | 0xC0040004 | 服务器无法在指定格式/请求的数据类型与规范数据类型之间转换数据。即服务器的数据类型与 IoTDB 的注册类型不一致。 | +| OPC\_E\_UNKNOWNITEMID| 0xC0040007 | 在服务器地址空间中未定义该条目ID（添加或验证时），或该条目ID在服务器地址空间中已不存在（读取或写入时）。即 IoTDB 的测点在服务器内没有对应的 itemID。 | +| OPC\_E\_INVALIDITEMID | 0xC0040008 | 该 itemID不符合服务器的语法规范。 | +| REGDB\_E\_CLASSNOTREG | 0x80040154 | 未注册类 | +| RPC\_S\_SERVER\_UNAVAILABLE | 0x800706ba | RPC服务不可用 | +| DISP\_E\_OVERFLOW | 0x8002000a | 超过类型的最大值 | +| DISP\_E\_BADVARTYPE | 0x80020005 | 类型不匹配 | + +### 2.5 使用限制 + +* 仅支持 COM，且仅能在 Windows 上使用 +* 重启后可能会推送少部分旧数据，但是最终会推送新数据 +* 目前仅支持树模型数据。 + +## 3. 使用步骤 +### 3.1 前置条件 +1. Windows 环境，版本 >= 8 +2. IoTDB 已安装且可正常运行 +3. OPC DA Server 已安装 + +* 以 Simple OPC Server Simulator 为例 + +![](/img/opc-da-3-1.png) + +* 双击某项，可以修改该项的名字（itemID），数据，数据类型等各个信息。 +* 右键某项，可以删除该项、更新值、以及新建项。 + +![](/img/opc-da-3-2.png) + +4. OPC DA Client 已安装 + +* 以 KepwareServerEX 的 quickClient 为例 +* 在 Kepware 中可以如下打开 OPC DA Client + +![](/img/opc-da-3-3.png) + +![](/img/opc-da-3-4.png) + + +### 3.2 配置修改 + +修改 server 配置，以避免 IoTDB 的写入 client 与 Kepware 的读取 client 连接到两个不同的实例而无法调试。 + +* 首先按 Win+R 键，在运行菜单内输入 `dcomcnfg`，打开 dcom 的组件配置： + +![](/img/opc-da-3-5.png) + +* 点击组件服务 -> 计算机 -> 我的电脑 -> DCOM 配置，找到`AGG Software Simple OPC Server Simulator`，右键“属性”： + +![](/img/opc-da-3-6.png) + +* 在`标识`内，将`用户账户`改为`交互式用户`。注意这里不要为`启动用户`，否则可能导致两个 client 分别启动不同的 server 实例。 + +![](/img/opc-da-3-7.png) + +### 3.3 clsID 获取 +1. 方式一：通过 DCOM 配置 获取 + +* 按 Win+R 键，在运行菜单内输入 `dcomcnfg`，打开 dcom 的组件配置； +* 点击组件服务 -> 计算机 -> 我的电脑 -> DCOM 配置，找到`AGG Software Simple OPC Server Simulator`，右键“属性”。 +* 在 `常规 `中可以获取该应用程序的 clsID，用于之后 opc-da-sink 的连接，注意不带大括号 + +![](/img/opc-da-3-8.png) + +2. 方式二：clsID 与 progID 也可以直接在 server 里获取 + +* 点击 `Help` > `Show OPC Server Info` + +![](/img/opc-da-3-9.png) + +* 弹窗中即可显示 + +![](/img/opc-da-3-10.png) + +### 3.4 写入数据 +#### 3.4.1 DA Server +1. 在 DA Server 内新建项，与 IoTDB 的待写入项的 name 与 type 保持一致 + +![](/img/opc-da-3-11.png) + +2. 在 Kepware 中连上该 server： + +![](/img/opc-da-3-12.png) + +3. 右键服务器新建组，组名任意： + +![](/img/opc-da-3-13.png) + +![](/img/opc-da-3-14.png) + +4. 右键新建 item，item 的名字为之前创建的名字 + +![](/img/opc-da-3-15.png) + +![](/img/opc-da-3-16.png) + +![](/img/opc-da-3-17.png) + +#### 3.4.2 IoTDB +1. 启动 IoTDB +2. 创建 Pipe + +```SQL +create pipe opc ('sink'='opc-da-sink', 'opcda.clsid'='CAE8D0E1-117B-11D5-924B-11C0F023E91C') +``` + +* 注意：如果创建失败，提示` Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 1107: Failed to connect to server, error code: 0x80040154`，则可以参考该解决方案进行处理：https://opcexpert.com/support/0x80040154-class-not-registered/ + +3. 创建时间序列（如果已开启自动创建元数据，则本步骤可以省略） + +```SQL +create timeseries root.a.b.c.r string; +``` + +4. 插入数据 + +```SQL +insert into root.a.b.c (time, r) values(10000, "SomeString") +``` + +### 3.5 验证数据 + +查看 Quick client 的数据，应该已经得到更新。 + +![](/img/opc-da-3-18.png) \ No newline at end of file diff --git a/src/zh/UserGuide/dev-1.3/API/Programming-OPC-DA_timecho.md b/src/zh/UserGuide/dev-1.3/API/Programming-OPC-DA_timecho.md new file mode 100644 index 000000000..435f28c80 --- /dev/null +++ b/src/zh/UserGuide/dev-1.3/API/Programming-OPC-DA_timecho.md @@ -0,0 +1,208 @@ + + +# OPC DA 协议 + +## 1. OPC DA + +OPC DA (OPC Data Access) 是工业自动化领域的一种通信协议标准，属于经典 OPC（OLE for Process Control）技术的核心部分。它的主要目标是实现 Windows 环境下工业设备与软件（如 SCADA、HMI、数据库）之间的实时数据交互。OPC DA 基于 COM / DCOM 实现，是一个轻量级的协议，分为服务器和客户端两个角色。 + +* **服务器：** 可以视为一个 Item 的池，存储各个实例的最新数据及其状态。所有 item 只能在服务器端管理，客户端只能读写数据，无权操作元信息。 + +![](/img/opc-da-1-1.png) + +* **客户端：** 连接服务器后，需要自定义一个组（这个组仅与客户端有关），并创建服务器的同名 item，然后可以对自身已创建的 item 进行读写。 + +![](/img/opc-da-1-2.png) + +## 2. OPC DA Sink + +IoTDB （V1.3.5.2及以后的V1.x版本支持） 提供的 OPC DA Sink 支持将树模型数据推送到本地 COM 服务器的插件，它封装了 OPC DA 接口规范及其固有复杂性，显著简化了集成流程。OPC DA Sink 推送数据流图如下所示。 + +![](/img/opc-da-2-1.png) + +### 2.1 SQL 语法 + +```SQL +---- 注意这里的 clsID 需要替换为自己的 clsID +create pipe opc ( + 'sink'='opc-da-sink', + --- 'opcda.progid'='opcserversim.Instance.1' + 'opcda.clsid'='CAE8D0E1-117B-11D5-924B-11C0F023E91C' +); +``` + +### 2.2 参数介绍 + +| **参数** | **描述** | **取值范围 ** | 是否必填 | +| ------------------- | --------------------------------------------------------------------- | ----------------------- | ------------------ | +| sink | OPC DA SINK | String: opc-da-sink | 必填 | +| sink.opcda.clsid | OPC Server 的 ClsID（唯一标识字符串）。建议使用 clsID 而非 progID。 | String | 和 progId 二选一 | +| sink.opcda.progid | OPC Server 的 ProgID，如果有 clsID，优先使用 clsID。 | String | 和 clsID 二选一 | + +### 2.3 映射规范 + +使用时，IoTDB 将会将自身的树模型最新数据推送到服务器，数据的 itemID 为树模型下的时间序列的全路径，如 `root.a.b.c.d`。注意根据 OPC DA 标准，客户端无权直接在 server 侧创建 item，因此需要服务器提前将 IoTDB 的时间序列以 itemID 和对应数据类型的格式创建为 item。 + +* 数据类型对应如下表所示。 + +| IoTDB | OPC-DA Server | +| ----------- | ----------------------------------------------------------- | +| INT32 | VT\_I4 | +| INT64 | VT\_I8 | +| FLOAT | VT\_R4 | +| DOUBLE | VT\_R8 | +| TEXT | VT\_BSTR | +| BOOLEAN | VT\_BOOL | +| DATE | VT\_DATE | +| TIMESTAMP | VT\_DATE | +| BLOB | VT\_BSTR（Variant 不支持 VT\_BLOB，因此用 VT\_BSTR 替代） | +| STRING | VT\_BSTR | + +### 2.4 常见错误码 + +| 符号 | 错误码 | 描述 | +| ----------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| OPC\_E\_BADTYPE | 0xC0040004 | 服务器无法在指定格式/请求的数据类型与规范数据类型之间转换数据。即服务器的数据类型与 IoTDB 的注册类型不一致。 | +| OPC\_E\_UNKNOWNITEMID| 0xC0040007 | 在服务器地址空间中未定义该条目ID（添加或验证时），或该条目ID在服务器地址空间中已不存在（读取或写入时）。即 IoTDB 的测点在服务器内没有对应的 itemID。 | +| OPC\_E\_INVALIDITEMID | 0xC0040008 | 该 itemID不符合服务器的语法规范。 | +| REGDB\_E\_CLASSNOTREG | 0x80040154 | 未注册类 | +| RPC\_S\_SERVER\_UNAVAILABLE | 0x800706ba | RPC服务不可用 | +| DISP\_E\_OVERFLOW | 0x8002000a | 超过类型的最大值 | +| DISP\_E\_BADVARTYPE | 0x80020005 | 类型不匹配 | + +### 2.5 使用限制 + +* 仅支持 COM，且仅能在 Windows 上使用 +* 重启后可能会推送少部分旧数据，但是最终会推送新数据 +* 目前仅支持树模型数据。 + +## 3. 使用步骤 +### 3.1 前置条件 +1. Windows 环境，版本 >= 8 +2. IoTDB 已安装且可正常运行 +3. OPC DA Server 已安装 + +* 以 Simple OPC Server Simulator 为例 + +![](/img/opc-da-3-1.png) + +* 双击某项，可以修改该项的名字（itemID），数据，数据类型等各个信息。 +* 右键某项，可以删除该项、更新值、以及新建项。 + +![](/img/opc-da-3-2.png) + +4. OPC DA Client 已安装 + +* 以 KepwareServerEX 的 quickClient 为例 +* 在 Kepware 中可以如下打开 OPC DA Client + +![](/img/opc-da-3-3.png) + +![](/img/opc-da-3-4.png) + + +### 3.2 配置修改 + +修改 server 配置，以避免 IoTDB 的写入 client 与 Kepware 的读取 client 连接到两个不同的实例而无法调试。 + +* 首先按 Win+R 键，在运行菜单内输入 `dcomcnfg`，打开 dcom 的组件配置： + +![](/img/opc-da-3-5.png) + +* 点击组件服务 -> 计算机 -> 我的电脑 -> DCOM 配置，找到`AGG Software Simple OPC Server Simulator`，右键“属性”： + +![](/img/opc-da-3-6.png) + +* 在`标识`内，将`用户账户`改为`交互式用户`。注意这里不要为`启动用户`，否则可能导致两个 client 分别启动不同的 server 实例。 + +![](/img/opc-da-3-7.png) + +### 3.3 clsID 获取 +1. 方式一：通过 DCOM 配置 获取 + +* 按 Win+R 键，在运行菜单内输入 `dcomcnfg`，打开 dcom 的组件配置； +* 点击组件服务 -> 计算机 -> 我的电脑 -> DCOM 配置，找到`AGG Software Simple OPC Server Simulator`，右键“属性”。 +* 在 `常规 `中可以获取该应用程序的 clsID，用于之后 opc-da-sink 的连接，注意不带大括号 + +![](/img/opc-da-3-8.png) + +2. 方式二：clsID 与 progID 也可以直接在 server 里获取 + +* 点击 `Help` > `Show OPC Server Info` + +![](/img/opc-da-3-9.png) + +* 弹窗中即可显示 + +![](/img/opc-da-3-10.png) + +### 3.4 写入数据 +#### 3.4.1 DA Server +1. 在 DA Server 内新建项，与 IoTDB 的待写入项的 name 与 type 保持一致 + +![](/img/opc-da-3-11.png) + +2. 在 Kepware 中连上该 server： + +![](/img/opc-da-3-12.png) + +3. 右键服务器新建组，组名任意： + +![](/img/opc-da-3-13.png) + +![](/img/opc-da-3-14.png) + +4. 右键新建 item，item 的名字为之前创建的名字 + +![](/img/opc-da-3-15.png) + +![](/img/opc-da-3-16.png) + +![](/img/opc-da-3-17.png) + +#### 3.4.2 IoTDB +1. 启动 IoTDB +2. 创建 Pipe + +```SQL +create pipe opc ('sink'='opc-da-sink', 'opcda.clsid'='CAE8D0E1-117B-11D5-924B-11C0F023E91C') +``` + +* 注意：如果创建失败，提示` Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 1107: Failed to connect to server, error code: 0x80040154`，则可以参考该解决方案进行处理：https://opcexpert.com/support/0x80040154-class-not-registered/ + +3. 创建时间序列（如果已开启自动创建元数据，则本步骤可以省略） + +```SQL +create timeseries root.a.b.c.r string; +``` + +4. 插入数据 + +```SQL +insert into root.a.b.c (time, r) values(10000, "SomeString") +``` + +### 3.5 验证数据 + +查看 Quick client 的数据，应该已经得到更新。 + +![](/img/opc-da-3-18.png) \ No newline at end of file diff --git a/src/zh/UserGuide/latest/API/Programming-OPC-DA_timecho.md b/src/zh/UserGuide/latest/API/Programming-OPC-DA_timecho.md new file mode 100644 index 000000000..f6dc7368d --- /dev/null +++ b/src/zh/UserGuide/latest/API/Programming-OPC-DA_timecho.md @@ -0,0 +1,208 @@ + + +# OPC DA 协议 + +## 1. OPC DA + +OPC DA (OPC Data Access) 是工业自动化领域的一种通信协议标准，属于经典 OPC（OLE for Process Control）技术的核心部分。它的主要目标是实现 Windows 环境下工业设备与软件（如 SCADA、HMI、数据库）之间的实时数据交互。OPC DA 基于 COM / DCOM 实现，是一个轻量级的协议，分为服务器和客户端两个角色。 + +* **服务器：** 可以视为一个 Item 的池，存储各个实例的最新数据及其状态。所有 item 只能在服务器端管理，客户端只能读写数据，无权操作元信息。 + +![](/img/opc-da-1-1.png) + +* **客户端：** 连接服务器后，需要自定义一个组（这个组仅与客户端有关），并创建服务器的同名 item，然后可以对自身已创建的 item 进行读写。 + +![](/img/opc-da-1-2.png) + +## 2. OPC DA Sink + +IoTDB （V2.0.5.1及以后的V2.x版本支持） 提供的 OPC DA Sink 支持将树模型数据推送到本地 COM 服务器的插件，它封装了 OPC DA 接口规范及其固有复杂性，显著简化了集成流程。OPC DA Sink 推送数据流图如下所示。 + +![](/img/opc-da-2-1.png) + +### 2.1 SQL 语法 + +```SQL +---- 注意这里的 clsID 需要替换为自己的 clsID +create pipe opc ( + 'sink'='opc-da-sink', + --- 'opcda.progid'='opcserversim.Instance.1' + 'opcda.clsid'='CAE8D0E1-117B-11D5-924B-11C0F023E91C' +); +``` + +### 2.2 参数介绍 + +| **参数** | **描述** | **取值范围 ** | 是否必填 | +| ------------------- | --------------------------------------------------------------------- | ----------------------- | ------------------ | +| sink | OPC DA SINK | String: opc-da-sink | 必填 | +| sink.opcda.clsid | OPC Server 的 ClsID（唯一标识字符串）。建议使用 clsID 而非 progID。 | String | 和 progId 二选一 | +| sink.opcda.progid | OPC Server 的 ProgID，如果有 clsID，优先使用 clsID。 | String | 和 clsID 二选一 | + +### 2.3 映射规范 + +使用时，IoTDB 将会将自身的树模型最新数据推送到服务器，数据的 itemID 为树模型下的时间序列的全路径，如 `root.a.b.c.d`。注意根据 OPC DA 标准，客户端无权直接在 server 侧创建 item，因此需要服务器提前将 IoTDB 的时间序列以 itemID 和对应数据类型的格式创建为 item。 + +* 数据类型对应如下表所示。 + +| IoTDB | OPC-DA Server | +| ----------- | ----------------------------------------------------------- | +| INT32 | VT\_I4 | +| INT64 | VT\_I8 | +| FLOAT | VT\_R4 | +| DOUBLE | VT\_R8 | +| TEXT | VT\_BSTR | +| BOOLEAN | VT\_BOOL | +| DATE | VT\_DATE | +| TIMESTAMP | VT\_DATE | +| BLOB | VT\_BSTR（Variant 不支持 VT\_BLOB，因此用 VT\_BSTR 替代） | +| STRING | VT\_BSTR | + +### 2.4 常见错误码 + +| 符号 | 错误码 | 描述 | +| ----------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| OPC\_E\_BADTYPE | 0xC0040004 | 服务器无法在指定格式/请求的数据类型与规范数据类型之间转换数据。即服务器的数据类型与 IoTDB 的注册类型不一致。 | +| OPC\_E\_UNKNOWNITEMID| 0xC0040007 | 在服务器地址空间中未定义该条目ID（添加或验证时），或该条目ID在服务器地址空间中已不存在（读取或写入时）。即 IoTDB 的测点在服务器内没有对应的 itemID。 | +| OPC\_E\_INVALIDITEMID | 0xC0040008 | 该 itemID不符合服务器的语法规范。 | +| REGDB\_E\_CLASSNOTREG | 0x80040154 | 未注册类 | +| RPC\_S\_SERVER\_UNAVAILABLE | 0x800706ba | RPC服务不可用 | +| DISP\_E\_OVERFLOW | 0x8002000a | 超过类型的最大值 | +| DISP\_E\_BADVARTYPE | 0x80020005 | 类型不匹配 | + +### 2.5 使用限制 + +* 仅支持 COM，且仅能在 Windows 上使用 +* 重启后可能会推送少部分旧数据，但是最终会推送新数据 +* 目前仅支持树模型数据。 + +## 3. 使用步骤 +### 3.1 前置条件 +1. Windows 环境，版本 >= 8 +2. IoTDB 已安装且可正常运行 +3. OPC DA Server 已安装 + +* 以 Simple OPC Server Simulator 为例 + +![](/img/opc-da-3-1.png) + +* 双击某项，可以修改该项的名字（itemID），数据，数据类型等各个信息。 +* 右键某项，可以删除该项、更新值、以及新建项。 + +![](/img/opc-da-3-2.png) + +4. OPC DA Client 已安装 + +* 以 KepwareServerEX 的 quickClient 为例 +* 在 Kepware 中可以如下打开 OPC DA Client + +![](/img/opc-da-3-3.png) + +![](/img/opc-da-3-4.png) + + +### 3.2 配置修改 + +修改 server 配置，以避免 IoTDB 的写入 client 与 Kepware 的读取 client 连接到两个不同的实例而无法调试。 + +* 首先按 Win+R 键，在运行菜单内输入 `dcomcnfg`，打开 dcom 的组件配置： + +![](/img/opc-da-3-5.png) + +* 点击组件服务 -> 计算机 -> 我的电脑 -> DCOM 配置，找到`AGG Software Simple OPC Server Simulator`，右键“属性”： + +![](/img/opc-da-3-6.png) + +* 在`标识`内，将`用户账户`改为`交互式用户`。注意这里不要为`启动用户`，否则可能导致两个 client 分别启动不同的 server 实例。 + +![](/img/opc-da-3-7.png) + +### 3.3 clsID 获取 +1. 方式一：通过 DCOM 配置 获取 + +* 按 Win+R 键，在运行菜单内输入 `dcomcnfg`，打开 dcom 的组件配置； +* 点击组件服务 -> 计算机 -> 我的电脑 -> DCOM 配置，找到`AGG Software Simple OPC Server Simulator`，右键“属性”。 +* 在 `常规 `中可以获取该应用程序的 clsID，用于之后 opc-da-sink 的连接，注意不带大括号 + +![](/img/opc-da-3-8.png) + +2. 方式二：clsID 与 progID 也可以直接在 server 里获取 + +* 点击 `Help` > `Show OPC Server Info` + +![](/img/opc-da-3-9.png) + +* 弹窗中即可显示 + +![](/img/opc-da-3-10.png) + +### 3.4 写入数据 +#### 3.4.1 DA Server +1. 在 DA Server 内新建项，与 IoTDB 的待写入项的 name 与 type 保持一致 + +![](/img/opc-da-3-11.png) + +2. 在 Kepware 中连上该 server： + +![](/img/opc-da-3-12.png) + +3. 右键服务器新建组，组名任意： + +![](/img/opc-da-3-13.png) + +![](/img/opc-da-3-14.png) + +4. 右键新建 item，item 的名字为之前创建的名字 + +![](/img/opc-da-3-15.png) + +![](/img/opc-da-3-16.png) + +![](/img/opc-da-3-17.png) + +#### 3.4.2 IoTDB +1. 启动 IoTDB +2. 创建 Pipe + +```SQL +create pipe opc ('sink'='opc-da-sink', 'opcda.clsid'='CAE8D0E1-117B-11D5-924B-11C0F023E91C') +``` + +* 注意：如果创建失败，提示` Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 1107: Failed to connect to server, error code: 0x80040154`，则可以参考该解决方案进行处理：https://opcexpert.com/support/0x80040154-class-not-registered/ + +3. 创建时间序列（如果已开启自动创建元数据，则本步骤可以省略） + +```SQL +create timeseries root.a.b.c.r string; +``` + +4. 插入数据 + +```SQL +insert into root.a.b.c (time, r) values(10000, "SomeString") +``` + +### 3.5 验证数据 + +查看 Quick client 的数据，应该已经得到更新。 + +![](/img/opc-da-3-18.png) \ No newline at end of file