Skip to content

Commit 2d4e5cd

Browse files
samson0vsamson0v
committed
Corrected grammar
1 parent a7fcf3c commit 2d4e5cd

File tree

1 file changed

+58
-58
lines changed

1 file changed

+58
-58
lines changed

‎docs/iot-gateway/config/odbc.md

Lines changed: 58 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,9 @@ description: ODBC support for ThingsBoard IoT Gateway
88
* TOC
99
{:toc}
1010

11-
This guide will help you to get familiar with ODBC connector configuration for ThingsBoard IoT Gateway.
11+
This guide help you get familiar with ODBC connector configuration for ThingsBoard IoT Gateway.
1212
Use [general configuration](/docs/iot-gateway/configuration/) to enable this connector.
13-
We will describe connector configuration file below.
13+
We will describe the connector configuration file below.
1414

1515
<b>Example of ODBC Connector config file.</b>
1616

@@ -76,42 +76,42 @@ We will describe connector configuration file below.
7676

7777
## Prerequisites
7878

79-
To install and get ODBC connector working several additional steps need to be done:
79+
To install and get ODBC connector working, several additional steps need to be done:
8080

8181
1. Install [Visual C++ Redistributable package](https://github.com/mkleehammer/pyodbc/wiki/Install#installing-on-windows) for Windows or [ODBC package](https://github.com/mkleehammer/pyodbc/wiki/Install#installing-on-linux) for Linux.
82-
2. Install ODBC driver(s) for database(s) the ThingsBoard gateway need to connect.
82+
2. Install ODBC driver(s) for database(s) the ThingsBoard gateway needs to connect to.
8383
3. Add data source in [ODBC Data source Administrator](https://docs.microsoft.com/en-us/sql/database-engine/configure-windows/open-the-odbc-data-source-administrator) on Windows or add driver information (name, library path etc.) to ODBC configuration file [odbcinst.ini](https://github.com/mkleehammer/pyodbc/wiki/Drivers-and-Driver-Managers#odbc-configuration-files-unix-only) on Unix systems.
8484

8585
## Section "connection"
86-
This **mandatory** section provides information how to connect or reconnect to ODBC database.
86+
This **mandatory** section provides information on how to connect or reconnect to ODBC database.
8787

88-
| **Parameter** | **Default value** | **Description** |
89-
|:-|:-|-
90-
| **str** | | Database [connection string](https://www.connectionstrings.com). |
91-
| attributes | | Connection [attributes](https://github.com/mkleehammer/pyodbc/wiki/Connection#connection-attributes). |
92-
| encoding | **utf-16** | Encoding used when writing string data to database. |
93-
| decoding | | Encoding configuration used when reading string data from database. |
94-
| reconnect | **true** | Whether to reconnect after catching database error. |
95-
| reconnectPeriod | **60.0** | Period in seconds between reconnect attempts. Floating point means more precise time than seconds. |
88+
| **Parameter** | **Default value** | **Description** |
89+
|:-|:------------------|-------------------------------------------------------------------------------------------------------
90+
| **str** | | Database [connection string](https://www.connectionstrings.com). |
91+
| attributes | | Connection [attributes](https://github.com/mkleehammer/pyodbc/wiki/Connection#connection-attributes). |
92+
| encoding | **utf-16** | Encoding is used when writing string data to database. |
93+
| decoding | | Encoding configuration is used when reading string data from database. |
94+
| reconnect | **true** | Whether to reconnect after catching database error. |
95+
| reconnectPeriod | **60.0** | Period in seconds between reconnect attempts. Floating point means more precise time than seconds. |
9696

97-
**Note**: More information about encoding/decoding read [there](https://github.com/mkleehammer/pyodbc/wiki/Unicode).
97+
**Note**: For more information about encoding/decoding, read [there](https://github.com/mkleehammer/pyodbc/wiki/Unicode).
9898

9999
### Subsection "attributes"
100-
This **optional** subsection provides [several options](https://github.com/mkleehammer/pyodbc/wiki/Connection#connection-attributes) to tune connection procedure.
100+
This **optional** subsection provides [several options](https://github.com/mkleehammer/pyodbc/wiki/Connection#connection-attributes) to tune the connection procedure.
101101

102102
### Subsection "decoding"
103-
This **optional** subsection provides information how to decode string data and metadata read from a database.
103+
This **optional** subsection provides information on how to decode string data and metadata read from a database.
104104

105-
| **Parameter** | **Default value** | **Description** |
106-
|:-|:-|-
107-
| char | **utf-16** | Encoding used when reading string data from database. |
108-
| wchar | **utf-16** | Encoding used when reading Unicode string data from database. |
109-
| metadata | **utf-16** | Encoding used when reading metadata from database. |
105+
| **Parameter** | **Default value** | **Description** |
106+
|:-|:-|------------------------------------------------------------------
107+
| char | **utf-16** | Encoding is used when reading string data from database. |
108+
| wchar | **utf-16** | Encoding is used when reading Unicode string data from database. |
109+
| metadata | **utf-16** | Encoding is used when reading metadata from database. |
110110

111111
**Note**: More information about encoding/decoding read [there](https://github.com/mkleehammer/pyodbc/wiki/Unicode).
112112

113113
## Section "pyodbc"
114-
This **optional** section provides [options](https://github.com/mkleehammer/pyodbc/wiki/The-pyodbc-Module#pyodbc-attributes) to tune *pyodbc* Python library which is working under the hood of ODBC Connector.
114+
This **optional** section provides [options](https://github.com/mkleehammer/pyodbc/wiki/The-pyodbc-Module#pyodbc-attributes) to tune the *pyodbc* Python library, which works under the hood of ODBC Connector.
115115

116116
```json
117117
"pyodbc": {
@@ -121,36 +121,36 @@ This **optional** section provides [options](https://github.com/mkleehammer/pyod
121121
```
122122

123123
## Property "converter"
124-
ODBC connector is provided with built-in uplink data converter. One can specify custom converter class in this **optional** property.
124+
ODBC connector is provided with a built-in uplink data converter. You can specify a custom converter class in this **optional** property.
125125

126126
```json
127127
"converter": "CustomOdbcUplinkConverter",
128128
```
129129

130130
## Section "polling"
131-
The main idea of ODBC connector is periodically querying ODBC database whether new data is appeared.
131+
The main idea of ODBC connector is in periodically querying ODBC database to check whether new data has appeared.
132132

133-
This **mandatory** section provides information how often to query database, what data to select and which database column is used to iterate over result.
133+
This **mandatory** section provides information on how often to query the database, what data to select, and which database column is used to iterate over the result.
134134

135-
| **Parameter** | **Default value** | **Description** |
136-
|:-|:-|-
137-
| query | | SQL select query to fetch data from database. |
138-
| period | **60.0** | Period of polling in seconds. Floating point means more precise time than seconds. |
139-
| iterator | | Iterator configuration. |
135+
| **Parameter** | **Default value** | **Description** |
136+
|:-|:------------------|------------------------------------------------------------------------------------
137+
| query | | SQL select query to fetch data from database. |
138+
| period | **60.0** | Period of polling in seconds. Floating point means more precise time than seconds. |
139+
| iterator | | Iterator configuration. |
140140

141141
**The requirements for the *query* option**:
142142

143-
1. Valid SQL *SELECT* statement that meets requirements of SQL dialect of the database the ThingsBoard gateway need to connect.
143+
1. Valid SQL *SELECT* statement that meets requirements of SQL dialect of the database the ThingsBoard gateway needs to connect to.
144144
2. Include *attributes* or/and *timeseries* columns in _SELECT_ list.
145-
3. Include the [*device*](/docs/iot-gateway/config/odbc/#subsection-device) column in _SELECT_ list to find out to which device data belongs to.
146-
4. Include the [*iterator*](/docs/iot-gateway/config/odbc/#subsection-iterator) column in _SELECT_ list.
145+
3. Include the [*device*](/docs/iot-gateway/config/odbc/#subsection-device) column in the _SELECT_ list to determine to which device data belongs to.
146+
4. Include the [*iterator*](/docs/iot-gateway/config/odbc/#subsection-iterator) column in the _SELECT_ list.
147147
5. Among other conditions SQL _WHERE_ clause must include the [*iterator*](/docs/iot-gateway/config/odbc/#subsection-iterator) condition.
148148
6. Among other sorting expressions SQL _ORDER BY_ clause must include the [*iterator*](/docs/iot-gateway/config/odbc/#subsection-iterator) sorting expression.
149149
7. It is *recommended* to use SQL _LIMIT_ clause to reduce memory consumption on each read from a database.
150150

151151
**Example**:
152152

153-
Each polling iteration the connector will read 10 records sorted by _ts_ column ([*iterator*](/docs/iot-gateway/config/odbc/#subsection-iterator)).
153+
For each polling iteration, the connector will read 10 records sorted by _ts_ column ([*iterator*](/docs/iot-gateway/config/odbc/#subsection-iterator)).
154154

155155
Each record consists of timeseries columns (*bool_v*, *str_v*, *dbl_v*, *long_v*), [device](/docs/iot-gateway/config/odbc/#subsection-device) column (*entity_id*) and [*iterator*](/docs/iot-gateway/config/odbc/#subsection-iterator) column (*ts*).
156156

@@ -164,19 +164,19 @@ LIMIT 10 (6)
164164
```
165165

166166
### Subsection "iterator"
167-
This **mandatory** subsection provides information on what database column is used to iterate through the result set, where to get the initial value of the iterator and whether to use iterator data between gateway work sessions.
167+
This **mandatory** subsection provides information on which database column is used to iterate through the result set, where to get the initial value of the iterator, and whether to use iterator data between gateway work sessions.
168168
<br>
169169
<br>
170170
**IMPORTANT**
171171

172172
The main challenge of the *iterator* feature is to unambiguously figure out whether to restore iterator data from a previous gateway work session or to use values from the connector configuration file.
173173

174-
Each *iterator* has its own file that has been stored in *config/odbc/* folder. After each polling iteration the connector saves *iterator* data (see below the *persistent* option) to such file.
174+
Each *iterator* has its own file that is stored in the *config/odbc/* folder. After each polling iteration the connector saves *iterator* data (see below the *persistent* option) to such file.
175175
<br>
176176
<hr/>
177-
*\- How does connector distinguish iterator files from each other?*
177+
*\- How does the connector distinguish iterator files from each other?*
178178

179-
\- The short answer is a decision is based on the *iterator* file name.
179+
\- The short answer: it is a decision is based on the *iterator* file name.
180180
<hr/>
181181
In details, once the connector starts and connects to a database it checks whether the *persistent* flag (see below) is set to *true*. If so the connector calculates the *iterator* file name and checks if it exists in *config/odbc/* folder.
182182

@@ -210,35 +210,35 @@ There may happen that while using the same database the list of **tables is tota
210210
**Note**: Options *value* and *query* are mutually exclusive. If both options are set _value_ will be used.
211211

212212
## Section "mapping"
213-
This **mandatory** section provides information how to map the result set that is get from a database to device attributes and timeseries values.
213+
This **mandatory** section provides information on how to map the result set received from a database to device attributes and timeseries values.
214214

215-
| **Parameter** | **Default value** | **Description** |
216-
|:-|:-|-
217-
| **device** | | Device configuration. |
218-
| sendDataOnlyOnChange | **false** | Sending only if data changed from last check, if not specified data will send after each polling iteration. |
219-
| attributes | | List of device attributes. |
220-
| timeseries | | List of time series keys. |
215+
| **Parameter** | **Default value** | **Description** |
216+
|:-|:------------------|--------------------------------------------------------------------------------------------------------------------------
217+
| **device** | | Device configuration. |
218+
| sendDataOnlyOnChange | **false** | Sends data only if it has changed from the last check, if not specified, data will be sent after each polling iteration. |
219+
| attributes | | List of device attributes. |
220+
| timeseries | | List of time series keys. |
221221

222222
### Subsection "device"
223-
This **mandatory** subsection provides information how to map the result set to **unique** device name and its type.
223+
This **mandatory** subsection provides information on how to map the result set to a **unique** device name and its type.
224224

225225
| **Parameter** | **Default value** | **Description** |
226226
|:-|:-|-
227227
| **name** | | Python [eval()](https://docs.python.org/3/library/functions.html#eval) expression to generate **unique** device name. |
228228
| type | **odbc** | ThingsBoard device type. |
229229

230-
**Note** All database columns listed in SQL *SELECT* clause of the [query](/docs/iot-gateway/config/odbc/#section-polling) option are available by its name in the Python [eval()](https://docs.python.org/3/library/functions.html#eval) context.
230+
**Note** All database columns listed in SQL *SELECT* clause of the [query](/docs/iot-gateway/config/odbc/#section-polling) option are available by their name in the Python [eval()](https://docs.python.org/3/library/functions.html#eval) context.
231231

232232
For example,
233233
```json
234234
"device": {
235235
"name": "'ODBC' + entity_id"
236236
}
237237
```
238-
,means that device name is a result of concatenating two strings: *ODBC* and the value of database column *entity_id*.
238+
means that the device name is a result of concatenating two strings: *ODBC* and the value of database column *entity_id*.
239239

240240
### Subsections "attributes" and "timeseries"
241-
These **optional** subsections provides information on what database columns are treated as attributes and what as time series keys and what pre-processing job should be done before sending to ThingsBoard server.
241+
These **optional** subsections provide information on which database columns are to be treated as attributes, which ones as time series keys, and what pre-processing tasks should be done before sending data to the ThingsBoard server.
242242

243243
The connector supports several configuration modes for these subsections:
244244

@@ -271,7 +271,7 @@ The connector supports several configuration modes for these subsections:
271271
| column | Database column name. |
272272
| value | Python [eval()](https://docs.python.org/3/library/functions.html#eval) expression to evaluate a value. |
273273

274-
**Note** All database columns listed in SQL *SELECT* clause of the [query](/docs/iot-gateway/config/odbc/#section-polling) option are available by its name in the Python [eval()](https://docs.python.org/3/library/functions.html#eval) context.
274+
**Note** All database columns listed in SQL *SELECT* clause of the [query](/docs/iot-gateway/config/odbc/#section-polling) option are available by their names in the Python [eval()](https://docs.python.org/3/library/functions.html#eval) context.
275275

276276
* combining mode
277277
```json
@@ -290,13 +290,13 @@ The connector supports several configuration modes for these subsections:
290290
, means treating all database columns as timeseries.
291291

292292
## Section "serverSideRpc"
293-
The connector is able to call SQL procedures/functions with or without parameters. Parameters are get either from a connector's configuration file or from [data](/docs/reference/gateway-mqtt-api/#server-side-rpc) received from a server.
293+
The connector is able to call SQL procedures/functions with or without parameters. Parameters are obtained either from a connector's configuration file or from [data](/docs/reference/gateway-mqtt-api/#server-side-rpc) received from a server.
294294

295-
| **Parameter** | **Default value** | **Description** |
296-
|:-|:-|-
297-
| enableUnknownRpc | **false** | Allow processing RPC commands not listed in *methods* subsection. |
298-
| overrideRpcConfig | **false** | Allow overriding RPC command configuration by data received from server.|
299-
| methods | | List of RPC methods and their parameters. |
295+
| **Parameter** | **Default value** | **Description** |
296+
|:-|:-|------------------------------------------------------------------------------
297+
| enableUnknownRpc | **false** | Allow processing RPC commands not listed in *methods* subsection. |
298+
| overrideRpcConfig | **false** | Allow overriding RPC command configuration by data received from the server. |
299+
| methods | | List of RPC methods and their parameters. |
300300

301301
The connector supports several configuration modes for the *methods* subsection:
302302

@@ -343,9 +343,9 @@ The connector supports several configuration modes for the *methods* subsection:
343343

344344
**IMPORTANT**
345345

346-
If *enableUnknownRpc* is set to *true*, [RPC params](/docs/reference/gateway-mqtt-api/#server-side-rpc) **must have** all needed **procedure/function configuration parameters**.
346+
If *enableUnknownRpc* is set to *true*, [RPC params](/docs/reference/gateway-mqtt-api/#server-side-rpc) **must include** all required **procedure/function configuration parameters**.
347347

348-
If *overrideRpcConfig* is set to *true*, [RPC params](/docs/reference/gateway-mqtt-api/#server-side-rpc) **may contain** all or some of **procedure/function configuration parameters** to override ones that are specified in the connector configuration file.
348+
If *overrideRpcConfig* is set to *true*, [RPC params](/docs/reference/gateway-mqtt-api/#server-side-rpc) **may contain** all or some of the **procedure/function configuration parameters** to override those specified in the connector configuration file.
349349

350350
**The order of arguments matters**. It must be the same as the order of parameters in SQL procedure/function.
351351
```json

0 commit comments

Comments
 (0)