Global Object CSV Files

From Control Solutions IoTServer Documentation
Revision as of 14:08, 20 May 2019 by Jimhogenson (talk | contribs)
Jump to navigation Jump to search

Global Object CSV Files

A CSV file may be imported to configure various aspects of the IoTServer (or Babel Buster gateway). A single CSV file may contain multiple sections. When a file including an “Objects” section is imported by the Data Engine, local objects will be configured. When a file including one or more “Modbus” sections is imported by an instance of the Modbus Engine, Modbus gateway functionality will be configured. The same Modbus file may be imported by a Modbus Client or Modbus Server, and either RTU or TCP, and only those sections of interest to that Modbus function will be imported. The CSV file may also contain one or more SNMP sections, and so forth.

A section begins when the word “Begin” appears in the first column of a line. All lines up to and including a line that begins with the word “End” will be taken to be part of that section.

The line immediately following the “Begin” line must be a header line. A Header line is one which labels the columns of data that will follow the Header line.

All lines following the Header line are data lines that are expected to contain the same number of columns as the Header line, and whose contents are defined by the labels found in each column of the Header line.

Labels in the section Begin and End lines, and labels in the Header line are NOT case sensitive and will be interpreted equally whether upper case, lower case, or some combination of both (for readability).

Labels may NOT contain embedded spaces. A label is terminated by a comma, line-end, or space. Labels may not be encapsulated in quote characters; however, data content in data lines may be encapsulated in quote characters and may contain embedded spaces or blanks if quoted.

Some labels in the Header line may be considered optional. The minimum required columns are indicated in the definition of each data section.

Columns in the Header line do not have to follow any particular order. They may be rearranged to the user’s liking. The only restriction is that data in subsequent data lines must match up with the labels placed in the Header line. Data lines may contain fewer columns than the Header line, but may not contain more. Data columns that the user wishes to deliberately omit, but omit between included columns, should be indicated by place holder commas (which will simply appear as blank cells in a spread sheet program).

A Begin line will contain three columns:
Column 1: BEGIN
Column 2: Function as noted below
Column 3: Sub-function as noted in definition of the Function.

Functions may be any of the following (with this listed expanded from time to time):

  • LOCALDATA
  • MODBUS
  • SNMP

Sub-functions:

MODBUS

  • DEVICES
  • READMAPS
  • WRITEMAPS
  • SERVERMAPS
  • SERVERREMAPS

NOTE: A Modbus CSV file may contain both client and server sections as the respective functionality will select sections relevant to its purpose. It should also be noted that the same application, csiModbusEngine, can function as both client and server (master and slave).

Global Objects CSV Example

The following illustrates a valid local object configuration CSV file. Columns omitted in any given line will assume default values.

Note: Pay special attention to quote characters. It is not necessary to explicitly include them when entering labels in the spread sheet program. The CSV export (file save as) will do that for you. More importantly, if you type them in manually, they will be the “fancy” version of quote characters and will be explicitly included in the resulting object name. Only the plain quotes inserted by the spread sheet program will be recognized as escape characters for embedded commas.

BEGIN,LOCALDATA,OBJECTS
NUMBER,TYPE,LENGTH,NAME,DESC,LOCATION,UNITS,REFRESH,DEFVALUE,DEFONSTART,PERSISTENT
1,INT,0,My object 1,Object 1 description,Location 1,No units,600,-99.000000,N,N
2,INT,0,My object 2,Object 2 description,Location 2,No units,600,-99.000000,N,N
3,INT,0,My object 3,Object 3 description,Location 3,No units,600,-99.000000,N,N
4,INT,0,"Thing 1,2,3",Object 4 description,Location 4,No units,600,-99.000000,N,N
11,REAL,0,Object name 11,Object 11 description,Location 11,No units,600,-99.000000,N,N
12,REAL,0,Object name 12,Object 12 description,Location 12,No units,600,-99.000000,N,N
21,CHAR,80,Object name 21,Object 21 description,Location 21,No units,0,0.000000,N,N
22,CHAR,80,Object name 22,Object 22 description,Location 22,No units,0,0.000000,N,N
END

LOCALDATA OBJECTS Data Section

For each object, the following data columns are recognized, with minimum required columns denoted “REQUIRED”:

Number – (REQUIRED) The local object number being defined (first object is 1).

Type – Valid parameters for type, referring to native data type, are as follows (CSV will assume integer if omitted):

Type label Description
Int 32-bit integer
Int64 64-bit integer
Real Floating point (double precision)
Char ASCII character string

Length – If type is “char”, then this specifies how many character long the string is. Not used for any type other than char. Length should be an integer. CSV import will assume maximum permitted value if omitted.

Name – Arbitrary name for the data object, generally visible in web UI’s. CSV import will insert “Object name N” if omitted.

Desc – Arbitrary description of the object provided by the user. CSV import will insert “Object N description” if omitted.

Location – Arbitrary location string further documenting the object. CSV import will insert “Location N” if omitted.

Units – Arbitrary units string further documenting the object. CSV import will insert “No units” if omitted.

Refresh – A timeout in seconds, if nonzero. If the object is not updated within this amount of time, its state will be changed to “stale”. If zero, the timeout feature is disabled and the object will never become stale. Timeout should be an integer. Will default to zero.

DefValue – Default value to be applied upon startup if requested, may be integer or real (but not character). Will default to zero.

DefOnTimeout - Flag set to "Y" to indicate that this object should be set to the default value upon refresh timeout.

DefOnStart – Flag set to “Y” to indicate that this object should be set to the default value at startup, or “N” otherwise (“N” assumed if omitted).

Persistent – Flag set to “Y” to indicate this object is “persistent”, which means saved in non-volatile memory. This non-volatile memory is implemented as a database stored in Flash memory. Upon startup, the object will assume its last known value as found in the database. Any changes to the object’s value will be recorded in the database for future use. If not persistent, set flag to “N” (“N” assumed if omitted).