Description of PiiGAB QuickPost

Chapter 0 About

This manual applies to Quickpost version >= 1.4.0
Requires MBusHub version >= 2.03.00

Manual version 2022-07-14

Chapter 1 File Formats

There are four file formats available. PiiGAB recommends using format 3 unless you are already using a system that depends on one of the other formats.

FORMAT1: Named EMC in earlier versions.

Header:

command=DEVICE_STATUS OK,PiiGAB importfil, Version 1.0

command=METER_READING delimiter=;

Content:

Channel_Device_Tag;Time Stamp;Value

where the Timestamp is on the format mm/dd/yyyy HH:MM:SS

Settings in csv file:
 
  • timeformat = 16 (mm/dd/yyyy HH:MM:SS)
  • TagType = 1 (Value)
  • TagType = 8 (Record) is enabled with version 1.03.02

Use pi900_intern_value.csv for testing.

Example:

command=DEVICE_STATUS
OK,PiiGAB importfil, Version 1.0

command=METER_READING delimiter=;
pi900_PIIa_FabricationNo;07/15/2019 08:53:12;16785480
pi900_PIIa_Voltage;07/15/2019 08:53:12;399
pi900_PIIa_Current;07/15/2019 08:53:12;0
pi900_PIIa_TimePoint8;07/15/2019 08:53:12;15.07.2019 08:53:12
pi900_PIIa_TimePoint16;07/15/2019 08:53:12;07/15/2019 08:53:12
pi900_PIIa_TimePoint24;07/15/2019 08:53:12;2019-07-15T08:53:12
pi900_PIIb_FabricationNo;07/15/2019 08:53:32;16785480
pi900_PIIb_Voltage;07/15/2019 08:53:32;399
pi900_PIIb_Current;07/15/2019 08:53:33;0
pi900_PIIb_TimePoint8;07/15/2019 08:53:39;15.07.2019 08:53:31
pi900_PIIb_TimePoint16;07/15/2019 08:53:39;07/15/2019 08:53:31
pi900_PIIb_TimePoint24;07/15/2019 08:53:40;2019-07-15T08:53:31

FORMAT2:

Header:No header
Content:Device;Time Stamp;Value

where the Timestamp is on the format mm/dd/yyyy HH:MM:SS Notice that if there are more than one tag per meter, they will be named the same in the result file.

Settings in csv file:
 
  • timeformat = 16 (mm/dd/yyyy HH:MM:SS)
  • TagType = 1 (Value)
  • TagType = 8 (Record) is enabled with version 1.03.02

Use pi900_intern_value.csv or pi900_intern_record.csv for testing.

Example:

PIIa;07/15/2019 08:56:14;16785480
PIIa;07/15/2019 08:56:14;399
PIIa;07/15/2019 08:56:14;15.07.2019 08:56:14
PIIa;07/15/2019 08:56:14;07/15/2019 08:56:14
PIIa;07/15/2019 08:56:14;2019-07-15T08:56:14
PIIb;07/15/2019 08:56:33;16785480
PIIb;07/15/2019 08:56:34;399
PIIb;07/15/2019 08:56:40;15.07.2019 08:56:33
PIIb;07/15/2019 08:56:41;07/15/2019 08:56:33
PIIb;07/15/2019 08:56:42;2019-07-15T08:56:33

FORMAT3:

Header:PiiGAB import file; FORMAT=3; Version=1.0
Content:Channel;Device;Tag;Configurable Time Stamp;Configurable value

The timestamp is configurable and is set by setting Device-option se more explanations in section Time Stamps:

The value is configurable as well by setting the TagType. TagType = 1 (Value) will output a single value like for the other formats. TagType = 8 (Record) will output a triple "Value;Unit;Medium" The record may become more configurable later.
Settings:
  • timeformat = 24 (8, 16 and 24 is allowed)
  • TagType = 8 (1 and 8 allowed)

Use pi900_intern_format3.csv for testing.

Example:

Start of file:
PiiGAB import file; FORMAT=3; Version=1.0

pi900;PIIa;FabricationNo;2019-07-15T10:16:57;16785480;; Fabrication No
pi900;PIIa;Voltage;2019-07-15T10:16:57;400E-1;V; Voltage
pi900;PIIa;Current;2019-07-15T10:16:57;0E-4;A; Current
pi900;PIIa;TimePoint8;2019-07-15T10:16:57;15.07.2019 10:16:57;; Time Point
pi900;PIIa;TimePoint16;2019-07-15T10:16:57;07/15/2019 10:16:57;; Time Point
pi900;PIIa;TimePoint24;2019-07-15T10:16:57;2019-07-15T10:16:57;; Time Point
pi900;PIIb;FabricationNo;2019-07-15T10:17:29;16785480;; Fabrication No
pi900;PIIb;Voltage;2019-07-15T10:17:29;399E-1;V; Voltage
pi900;PIIb;Current;2019-07-15T10:17:30;0E-4;A; Current
pi900;PIIb;TimePoint8;2019-07-15T10:17:36;15.07.2019 10:17:28;; Time Point
pi900;PIIb;TimePoint16;2019-07-15T10:17:36;07/15/2019 10:17:28;; Time Point
pi900;PIIb;TimePoint24;2019-07-15T10:17:37;2019-07-15T10:17:28;; Time Point

FORMAT4:

Filename:

This format sets the filename as well as its content.

filename = <user defined value>_yyyymmddTHHMMSS.csv

Example: myfile_20190715T154022.csv

Header:

No header

Content:

Channel;Channel_Device;ISO8601 timestamp;Floating point value

The floating point value should be a normal floating point 0.003234 not with exponent, 3.234E-3. EXPERIMENTAL: Column 2 is Channel_Device if tag = "value". If tag is not equal to "value", column 2 is Channel_Device_Tag.

Example:

Settings:
  • Device-Option [Device col 24] = 24 (yyyy-mm-ddTHH:MM:SS), 26 for telegram timestamp
  • TagType [Tag col 20] = 8 (Value;Unit;Medium)
  • Device-Option0 [Device col 21] = "f" for Floating point value readout

Use pi900_intern_format4.csv for testing.

Start of file:
pi900;pi900_PII12345678_FabricationNo;2019-07-15T10:27:07;16785480
pi900;pi900_PII12345678_Voltage;2019-07-15T10:27:07;39.900002
pi900;pi900_PII12345678_Current;2019-07-15T10:27:07;0.000000
pi900;pi900_PII12345678_ExtTemp;2019-07-15T10:27:07;32.599998
pi900;pi900_PII12345678_ExtTemp1;2019-07-15T10:27:07;33.799999
pi900;pi900_PII12345678_TimePoint0;2019-07-15T10:27:07;15.07.2019 10:27:07
pi900;pi900_PII12345678_TimePoint1;2019-07-15T10:27:07;07/15/2019 10:27:07
pi900;pi900_PII12345678_TimePoint4;2019-07-15T10:27:07;2019-07-15T10:27:07
pi900;pi900_PII12345678_FabricationNo;2019-07-15T10:27:26;16785480
pi900;pi900_PII12345678_Voltage;2019-07-15T10:27:27;39.900002
pi900;pi900_PII12345678_Current;2019-07-15T10:27:28;0.000000
pi900;pi900_PII12345678_ExtTemp;2019-07-15T10:27:31;32.900002
pi900;pi900_PII12345678_ExtTemp1;2019-07-15T10:27:32;33.799999
pi900;pi900_PII12345678_TimePoint0;2019-07-15T10:27:33;15.07.2019 10:27:26
pi900;pi900_PII12345678_TimePoint1;2019-07-15T10:27:34;07/15/2019 10:27:26
pi900;pi900_PII12345678_TimePoint4;2019-07-15T10:27:35;2019-07-15T10:27:26

EXPERIMENTAL behavior.
if the tag is set to "value", column 2 will be pi900_PII12345678, the "value" is not displayed.

Chapter 2 Time Stamps

2.1 Time Format

The Time Format can be set by the setting the Device-Option (Column 24) in the following way:

timeformat = 8,  Timestamp = yyyy.mm.dd HH:MM:SS Default
timeformat = 16, Timestamp = mm/dd/yyyy HH:MM:SS
timeformat = 24, Timestamp = yyyy-mm-ddTHH:MM:SS

The timestamps are by default set by Quickpost as the time of reading from meter. This is good enough for wired meters because the value is up to date unless an excessive cache time has been set in MBusHub. It may be good to know that for wireless meters, the measurement is cached for a few minutes inside the meter even if telegram is sent every half minute. The same value is sent several times.

For wireless meters this type of timestamping may be acceptable if the telegram is received every time but that cannot be guaranteed. The sending of telegrams may be infrequent or even a meter may have stopped working but the last telegram can be cached for up to months. Quickpost should therefore be configured to use a timestamp from the meter telegram in the following way.

  1. Make an OPC-Item named Channel.Device.time
  2. Add 2 to the Device-Option to (2 + timeformat)
  3. Set the Tag-Option2 equal to Device-Option for the .time tag.

The Pi-900S/T wireless programm will set datarecord 4 as a timestamp, stamped when the wireless telegram arrives and not updated until the arrival of a new telegram. This is simple to configure, the time item can be used for every meter.

Example:

The value is read out as a record. The timestamp must be read as a value. The format is 16 (mm/dd/yyyy HH:MM:SS). This will read a value and timestamp correctly from the Pi-900 (MBusHub >2.03.00).

[Device],pi900,,intern,,,,,,,,,,1,,,,,,251,,,,,18,,,,,
[Tag],pi900,,intern,value,,,,,,,,,,,,,,,5,8,8,1,,,,,
[Tag],pi900,,intern,time,,,,,,,,,,,,,,,11,1,8,1,,18,,,,,

Some wireless nodes don't add a timestamp to the telegram. The meter timestamp should then be used if it exists. If the timestamp is a normal M-Bus datarecord, this can be easily done from the example above.

However if the timestamp is in the manufacturer specific area, then it is recommended that you contact the PiiGAB support for help on making a meter template.

In MBusHub >2.03.00, a timestamp has been added as datarecord 11.

Chapter 3 Configuration options

File Name:

Name of result file. The result file will be saved under this name in the backup directory with an added timestamp, see definitions above. Please avoid spaces in the filename.

Format:

Format of files sent from Quickpost. The format is not fully defined by setting the format. The configuration (CSV) file must be set correctly as well. See format definitions above.

Upload Method:

Supported upload methods are HttpPost (http and https) and Ftp (ftp and sftp). The https and sftp methods need security setup. See below.

SFTP Private Key Auth:
 

Set to Yes if SFTP is used with SSH (Secure Shell) private key authentication is used.

Private Key:

Select SSH private key

Use Certificate File:
 

Set to yes if you want to use your own Certificate file rather than the certificates on the unit.

Certificate file:
 

Select SSL certificate file.

Server IP:

Set IP-number or IP-address of upload server (example.com). The ftp, sftp, http, https prefix is set automatically. Note: If IP-address is used, be sure that a DNS server is set if the network is static.

Path:

Path on the upload server.

Note: For SFTP. Quickpost will assume it is uploaded to the user directory. Start with "/" and add the full path if this it not expected. Example: path = test equals /home/user/test and ~/test but path = /test will start at root.

Remote Port:

Set if you are using non standard port for the corresponding upload method. Otherwise leave empty.

User Name:

Upload server user name.

Password:

Upload server password or private key password.

M-Bus Ascii Server IP:
 

This should be set to 127.0.0.1 (localhost)

Port:

UDP portnumber of the MBusAscii slaveport on MBusHub. MBusHub Slaveport 2 is recommended.

MBusAscii Station ID:
 

Be sure it is set to 0 on the MBusHub Slaveport.

Read Timeout:

Read timeout in seconds. Must be longer than than the MBusHub slaveport timeout.

N Bad Reads:

Number of repeated read requests.

Configuration File:
 

CSV configuration file. All OPC-items in this file must be defined in this file must be set in the MBusHub Masterport configuration file. MBusHub must be restarted if changes in this file are made.

:Upload Time [HH:MM]

Upload time once every day in Universal Time. This value is used if Upload Period is set to 0, see below.

Read Period [min]:
 

Period of readout in minutes. This value can be set per OPC-item in the CSV file. If set in the csv file, this value will be overridden.

Offset [min]:

Offset of readout from read period. Can be set in CSV file, see Read Period.

Upload Period [min]:
 

Upload period in minutes. Set to 0 if upload once a day at a specific time is wanted.

Keep Files [Days]:
 

Number of days before the upload file backup copies are removed. 0 means the files are kept forever.

Enable QuickPost:
 

Set to yes to enable QuickPost.

Read & Upload at startup:
 

Set to Yes if meters shall be read and upload files sent when QuickPost is restarted.

Save and Restart:
 

Save configuration and restart Quickpost.

Restart:

Restart QuickPost without saving the configuration file.

Chapter 4 Security

The https support has been improved in version 1.3.10. CA-certificate bundle has been added to the Pi-900. The user can upload its own certificate if needed.

There is SFTP support for both password and public/private authentication. Private keys with password are not supported yet.

To set it up, do the following:

  1. Update Known Host

Go to Quickpost->Security->SSH/SFTP Host Key management

Start by updating the known hosts with only the server IP. The status will be "Host Key OK, Warning! Unverified" meaning that the server did respond but its fingerprint has not been compared with a known fingerprint.

It is important to verify the fingerprint to avoid "man in the middle attack". To find the host key fingerprint. You can log into the server and do the following command:

ssh-keygen -lf <(ssh-keyscan localhost)

which returns something like:

3072 SHA256:HLkCYxTRqAMlV0yjgR4pWuARtRUWKQpjZxehqsnQIlo localhost (RSA)

256 SHA256:wLe7x7fOLL59zi80U5E1zKVhvOGFDxeR49SXaS4IZP0 localhost (ECDSA)

256 SHA256:7VZj4TWwZ/JrC3TIiu8E98SGpAzu0UuQDnMtGy/rd8I localhost (ED25519)

Verify with the known keys and you will get "Host Key OK, Verified".

You need to obtainn the server fingerprint in a secure way. Logging into the server, from a secure webpage or on paper but not by asking the server for its fingerprint through ssh.

  1. Create a public/private key pair

Go to Quickpost->Security->SSH/SFTP Host Key management

Click on "Generate SFTP key pair". This will create mykey and mykey.pub. You can set a key Password.

  1. Select private key/password

Go to Quickpost->Configure.

Set username.

If using private key set "SFTP Private Key Auth" to "Yes" and select correct "Private Key". If the private key is password locked, set its password in the password field.

Chapter 5 Example Server

PiiGAB have a FTP server which you can use in test purpose. Follow the steps in the list below if you want to try sending meter data with the FTP protocol.

  1. Set the configuration in Quickpost as the table below and press "Save and Restart".

    Quickpost Field Data
    Upload Method Ftp
    Server IP www29.fsdata.se
    User Name piigab-quickpost
    Password quickpost
  2. Press "List Files" in the top of the Quickpost page.

  3. When the file have been read out and sent to the FTP server the file should be shown under the: "Result files. Stored files that have been successfully uploaded". The filename have been appended with date.

  4. Now you can login to PiiGAB's FTP server to check if your files uploded correctly. We recommend using WinSCP. More advanced user can login over ftp using the command prompt.

Chapter 6 Error Codes

Code Error codes from MBusHub
C Error in checksum
D Wrong datatype. Datatype must be VT_BSTR.
I Unknown OPC-item. Quickpost reads an OPC-item which are not included in the MBusHub Maserport CSV-file
M Timeout MBusHub masterport. The meter do not respond
O Too many OPC-items at the same request.
T Timeout slaveport. No response from MBusHub masterport.
V Writing outside accepted value-area. Eg. Area 10-20 do not accept value 22.
Code Error codes from Quickpost
s Timeout in the Quickpost MBusAscii client.
q Incorrect TID.
p Incorrect PID.
c Error in checksum.

Chapter 7 Version information

1.3.10

  • Implementation of TLS1.2 and CA-bundle for httppost