Reference information

Implementation guidelines

The CMe/CMi Series gives a wide range of implementation possibilities. This chapter covers good implementation practice and method selection depending on customer needs.

Without any development needed, the product may be configured using SMS and Telnet. This may not be the most effective way when handling a high volume of products. Using Elvaco hosted configuration profiles or implementing a product configuration server, the product can be configured using HTTP web server requests.

Please see the user manuals of the CMe/CMi Series, for all the commands, configuration keys, syntax and reference information.

Implementation level

Elvaco has divided product implementation into four levels. These levels are defined to illustrate the time for implementation and give the developer a good understanding where to start the implementation process and select the correct level of functionality.

Table 130. Implementation levels

Implementation level

Level of functionality

Typical time for implementation

Level 1

Transparent M-Bus communication using GSM CSD or TCP/IP on GPRS network.

Configuration of the product is done by predefined configuration profile from Elvaco web server or by using SMS or Telnet.

0 hours

Using standard M-Bus master software

Level 2

Handle automatic scheduled pushed (E-Mail, FTP, HTTP) reports to retrieve meter values.

Configuration of the product is done by predefined configuration profile from Elvaco web server or by using SMS or Telnet.

8-16 hours

Level 3

Two way communication for configuration and starting commands using SMS.

Configuration can also be done by predefined configuration profile from Elvaco web server.

8-16 hours

Level 4

Configuration of the product using HTTP web server from customer implemented configuration server.

8-16 hours


Implementation level 1

When using transparent M-Bus communication, there are numerous software applications available on the market. The product handles transparent M-Bus communication according to the M-Bus standard, but the request/response time delays must be adjusted to handle GSM/GPRS network response times. Depending on network provider, the response time can differ. A good recommendation for a maximum response time between request/response is approximately 4 seconds.

From factory the product is listening and will answer all incoming GSM CSD calls and open for transparent M-Bus communication. The TCP/IP transparent M-Bus communication must be manually started using command qset tmbus1/tmbus2 on.

Implementation level 2

Depending on IT structure of implementation platform, reports can be received from the product using EMail, FTP and HTTP. In some cases, implementation using E-Mail and FTP may be the preferable. If the goal is to reach implementation level 4, HTTP should be used as the transfer protocol from start.

Receiving reports using E-mail

When installing the product, the default setting is to send hourly value reports. The report format can be configured using command cfg, see CMe/CMi Series user manuals. When receiving E-mail reports with meter data, rules can be set up, e.g. in MS Outlook to organize E-mails as needed. There are also software applications available on the market, which takes attached files and stores these files in a folder on a disk. WatchDirectory, https://www.watchdirectory.net, is one of the applications, which can handle these kinds of operations.

Requirements

For the product to be able to send E-mail reports, a SIM card with GPRS or LTE, depending on the product, must be used. The product also needs an SMTP server to send the reports. The SMTP server is normally automatically detected, but in some rare cases the server must be set manually using command qset email, see the user manuals of the CMe Series.. The command is also used to set E-mail recipients.

Report formats

There is a wide range of E-mail reports available. The major difference between different E-mail reports are:

  1. if the meter data should be attached as a file instead of printed in the body

  2. if the meter data should be sent in one file or separated in one file per device (meter)

  3. if the meter data should be decoded and readable or in raw M-Bus data format

Report template 1104 is a recommended choice if the report should be in machine friendly decoded format.

Report template 1103 can be used if the receiving system handles raw M-Bus data format.

Receiving reports using FTP

FTP (File Transfer Protocol) is widely used all over the world. This may be the choice when the integration platform has an external FTP server available. The product is using passive mode FTP, which resolves the problem of NATed TCP/IP traffic from a GPRS network to the internet.

Requirements

For the product to be able to send FTP reports, a SIM card with GPRS enabled must be used. The product must be configured where to send FTP reports, which can be set using command qset ftp, see the user manuals of the CMe Series. Username, password, port and default upload directory can also be set using the command qset ftp. The receiving FTP server must handle passive FTP. This may be disabled by firewall options. Verify firewall settings for passive FTP and FTP server application for a proper configuration.

Report formats

There is a wide range of FTP reports available. The major difference between FTP reports are:

  1. if the meter data should be sent in one file or separated in one file per device (meter)

  2. if the meter data should be decoded and readable or in raw M-Bus data format

Report template 2104 is a recommended choice if the report should be in machine friendly decoded format.

Report template 2103 can be used if the receiving system handles raw M-Bus data format.

Receiving reports using HTTP

HTTP (Hypertext Transfer Protocol) is widely used all over the world. This may be the choice when the integration platform has an external web server available. The product is using HTTP POST to send data to the server.

Requirements

For the product to be able to send HTTP reports, a SIM card with GPRS enabled must be used. The product must be configured where to send the HTTP reports. This can be set using command qset http, see the user manuals of the CMe series. Username, password, port and URL can also be set using the command qset http. HTTPS can be used for securing the connection, which is accomplished by entering the https instead of http in the URL on the web server.

The reports sent from the product to the web server are generated on runtime, which implies that the content length of the post is unknown when the HTTP headers are sent. Therefore the receiving web server must be able to handle chunked transfer encoding. This is usually not an issue when using Microsoft IIS or Apache web server, where chunked transfer encoding i handled automatically.

Report formats

There is a wide range of HTTP reports available. The major difference between HTTP reports are:

  1. if the meter data should be sent in one post or separated in one post per device (meter)

  2. if the meter data should be decoded and readable or in raw M-Bus data format

Report template 3104 is a good choice if the report should be in machine friendly decoded format.

Report template 3103 can be used if the receiving system handles raw M-Bus data format.

Implementation level 3

When the product is operational and sends reports automatically, there may still be situations when the server application needs to request or send data to the product. This can be accomplished by sending SMS to the product. The SMS can be a command to start a report manually, to start a configuration process with a web server or to change configuration.

SMS may not be the most reliable communication protocol, but to use SMS as a source to add extra information can be an efficient method for integration.

Sending SMS to the product

In the CMe/CMi Series User's Manual, all commands which can be sent using SMS is tagged with access “SMS”. When the product receives an SMS, following process is started:

  1. If phone number security is enabled, is the sending phone number accepted?

  2. Is the first line of the SMS a password for security level 1,2 or 3? If true, set proper security level.

  3. If 1) and 2) is parsed successfully, start parsing SMS command lines which can divided with CRLF or semi-colon “;”

  4. If the configuration key common.sms.response.mode is not set to disable responses, respond with the executed command response information. The default value for common.sms.response.mode is “all”.

Disable responses

In some cases, the SMS response from the product may not be of interest for the sending part. An example would be if the command is to start sending an HTTP POST report to a web server. This is automatically acknowledged when the report is received by the web server, therefore the SMS response will not contribute with any extra information. Override the sms.response.mode configuration by setting the value to none.

An example for starting command report1 and disable SMS responses would look like:

report1 sms.response.mode=none

Requesting meter data between two dates

This example describes how to start a report and send meter data within two dates.

To resend meter data between 2010-09-01 and 2010-09-03 with report template 1104, send the following SMS command:

Report 1104 filter.mode=interval filter.param=20100901,20100903

Change configuration of retries for report1

This example describes how to change the report retries and the time between the retries.

To set number of retries to ten (9) and time between retries to five (5) minutes, send the following SMS command:

set report1.schedule.retrymax=9 report1.schedule.retryoffset=300

The CMe/CMi Series User’s Manuals covers all this information in more detail. There is also numerous examples for every command which can be sent to the product.

Implementation level 4

Implementation level 4 is a combination of implementation level 3 and adding a product configuration server, which handles the distribution/product requests for a new or updated configuration. The product connects to the products configuration server when using command sync and using command install with suffix.

Following SMS command will force the product to execute command install and connect to Elvaco distribution server, by default, and download configuratin elvaco.

Install 1 elvaco

Following SMS command will force the product to execute sync and connect to Elvaco configuration server (by default), and download configuration “elvaco”.

Sync elvaco

Command install is used when installing the product for the first time or when meter configuration has changed. Command sync is used only when new configuration should be downloaded to the product.

The configuration “elvaco” is concatenated with the common.system.cota.urlbase to download the actual file from the configuration server. The actual url for configuration “elvaco” would be:

http://dist.elvaco.se/sync/cota/elvaco.cad.

Changing or overriding which configuration server to synchronize configuration with

From factory default, the product will connect to http://dist.elvaco.se/ for synchronizing configuration. This server setting can be changed using one of following configuration keys; common.system.cota.urlbase, common.system.cota.url, common.system.cota.user, common.system.cota.password, common.system.cota.authmode. The configuration key, urlbase, is used to set the base url when using short names in command install and sync. The configuration key, url, can be used to point out a specific location of a configuration file.

Example of executing sync and download a configuration file called myconfig.cad at http://myserver.com:

Sync system.cota.url=http://myserver.com/myconfig.cad.

Synchronization flow

The CMe/CMi Series starts with requesting a synchronization file. The synchronization file contains parameters to synchronize files and configuration keys to set in the product. When the synchronization of files and configuration are complete (or incomplete), the product will send a result to a specified result server. The result server can be specified in the cad file.

HTTP GET/POST

To identify the product, the HTTP header User-Agent is filled with the following information:

User-Agent= TC65i/<imei> Profile/IMP-NG Configuration/CLDC-1.1 Model/<model> Hardware/<hw> Firmware/<fw> Application/<sw> Serial/<serial>

Table 131. Parameter description

Parameter

Description

<imei>

15 digit product module IMEI number

<model>

Product model, i.e. CMe1000, CMe1100, CMe2000, CMe2100

<hw>

Product hardware version, i.e R4A

<fw>

Product module firmware version, i.e. 01.100

<sw>

Product software version, i.e. 1.1.0

<serial>

10 digit product serial number, i.e. 0006000000


Synchronization file
Cad file

The cad file contains the actual information to synchronize. All cad files must have the extension .cad.

See the following tables for synchronization parameters.

Table 132. Synchronization file (cad file)

Parameter

Description

Sync-Mode

Synchronization mode, must be set to “server”

Syntax:

Sync-Mode: server

Sync-Notify-URL

Result server URL. Notifications will be sent to this server address. Can be left out.

Syntax:

Sync-Notify-URL:

Sync-File-[0..n]-URL

Files to synchronize. The index must start at 0 and be continuous. Can be left out.

Syntax:

Sync-File-[0..n]-URL:<remote url>,<local file>

Sync-Config-[0..n]

Configuration keys and values to synchronize. The index must start at 0 and be continuous. Can be left out.

Syntax:

Sync- Config-[0..n]: <key>=<value>

Sync-Id

Identification which will be parsed into the result notification. Can be left out.

Syntax:

Sync-Id: <id>


Table 133. Parameter descriptions for cad-files

<notify url>

URL where to post notifications

<remote file>

URL where to get remote file

<local file>

Local path and filename where to put downloaded file

<key>

Configuration key to set

<value>

Configuration key value

<id>

User specific identification for this synchronization


Example of cad file

Sync-Mode: server

Sync-Id: 1

Sync-Notify-URL: http://dist.elvaco.se/RequestLogger/index.aspx

Sync-Config-0: common.branding.company=Elvaco AB

Sync-Config-1: common.branding.address1=Energigatan 9

Result notifications

If the parameter Sync-Notify-Url is set in the cad file, the product will post result information to given URL. The post is a standard HTTP post with a body containing the result information.

See the following table for possible results.

Table 134. Result notification post

Result

Description

900 Success

Synchronization completed successfully

920 Incompatible synchronizing mode

The Sync-Mode was not set to “server”

921 Error synchronizing files. <error>

Generic synchronization error.


Example of a notify post result body

900 Success Sync-Id: 1

Configuration keys and valid values

The configuration keys and values set in the configuration file must be valid. If any key or value is invalid, the configuration process will quit and an error message will be sent to initiator and to the result server.

Starting synchronization using SMS

Example 1. Example of starting synchronization using SMS with customer specified configuration server

Following configuration keys will be set:

  • report1.schedule.retrymax

  • report1.schedule.retryoffset

The Sync-Id is set to 1234 and will be posted back to the result server for identifying the configuration.

The configuration file url is set to http://myserver.com/config/myconfig.cad.

The result server url is set to http://myserver.com/result/result.html

SMS to the product to start synchronization:

Sync system.cota.url=http://myserver.com/config/myconfig.cad

SMS from the product indicating synchronization started

Sync started. OK

The product will download the configuration file using HTTP GET and set the configuration keys as specified.

The file myconfig.cad contents which will be downloaded to the product :

Sync-Mode: server

Sync-Id: 1234

Sync-Notify-URL: http://myserver.com/result/result.html

Sync-Config-0: report1.schedule.retrymax=10

Sync-Config-1: report1.schedule.retryoffset=600

After the configuration file is processed, the product will send a HTTP POST with the result information.

The HTTP POST body contents sent to the result server:

900 Success

Sync-Id: 1234


Report templates

Report templates are description files on how to format and send data from CMe/CMi Series products to an external source. Templates are available for SMS, FTP, HTTP and E-mail.

The report engine in CMe/CMi Series is powerful and can format almost any output data. Example of data format is csv formatted files, xml based data and human readable html reports. The report data can be events, meter data, system log reports etc.

CMe/CMi Series products are released with a standard set of reports, but can be enhanced by Elvaco provided add-ons and customer specific add-ons. Customer specific add-ons are not listed in this document.

Report template identifications

Assigned

Range

Name

0001-0999

Standard SMS reports

1000-1099

Standard E-Mail system reports

1100-1199

Standard E-Mail value reports

1500-1599

Add-on E-Mail reports

2000-2099

Standard FTP system reports

2100-2199

Standard FTP value reports

2500-2599

Add-on FTP reports

3000-3099

Standard HTTP system reports

3100-3199

Standard HTTP value reports

3500-3599

Add-on HTTP reports

9000-9999

Plugin reports

xx0001-xx0999

Customer specific SMS reports

xx1000-xx1099

Customer specific E-Mail system reports

xx1100-xx1199

Customer specific E-Mail value reports

xx2000-xx2099

Customer specific FTP system reports

xx2100-xx2199

Customer specific FTP value reports

xx3000-xx3099

Customer specific HTTP system reports

xx3100-xx3199

Customer specific HTTP value reports

Where xx is an Elvaco assigned customer number, two digits 00-99.

Plugin

Range

Name

9001-9009

DLMS System Report Template

9010-9019

DLMS Value Report Template

Definitions

Properties of a report value

Value reports contain meter report data. The CMe/CMi Series products can handle any standard M-Bus meter, which forces the product to dynamically assign properties for each available meter value. The properties are build up upon the internal M-Bus decoder. The properties are taken from the standard M-Bus EN13757. Within one telegram shall a combination of all properties for a value of a specific meter be unique, but sometimes M-Bus slave implementations don’t follow these recommendations. In those cases one or more values can have the exact same properties, but the position of the value is not unique which must be used to distinguish the values. The property names are globally used in all CMe/CMi Series documentation to describe i.e. report formats.

Table 135. Properties describing the origin of a value

Name

Description

Serial-number

The product serial number which has read and stored the value of a meter.

Device-identification

The M-Bus slave secondary identification which a value belongs to.

Date

The create date of a value.

Value-data-count

The M-Bus telegram in which a value was found.


Table 136. Properties describing the definition of a value

Name

Description

Description

Description of the value. This property is usually defining the type of the value, i.e. energy, flow temperature etc.

Unit

Unit of the value. This property defines the unit, i.e kWh, °C etc.

Function

Function of the value describing i.e min value, max value etc.

Tariff

The tariff of the value.

Sub unit

The sub unit of the value, i.e. a numeric value for extended information of a value.

Storage number

The storage number of the value. Normally describing historic values.


Serial number property

The serial number is an 10-digit long numeric value. The first 4-digits identifies the product type. An example of a serial-number from a CMe2100 product would look like: 0006xxxxxx, where xxxxxx is the actual serial number of the product.

Table 137. Product type numbers

Product

4-digit type number

CMe2100

0006

CMi2110

0012

CMi2120

Internal antenna

0029

CMi2120

External antenna

0027

CMi2130

0030

CMe3100

0016


Device-identification property

Device-identification is the unique meter id (M-Bus secondary address) which the meter value was read from. The device-identification is an 8-digit number. This number can normally be changed by the customer on demand. The device-identification for a meter is internally used in CMe/CMi Series to bind information for one meter connected to a CMe/CMi Series product. Thus all meters connected to CMe/CMi Series product must have unique device-identification (secondary address).

Data property

Date is the timestamp of the meter value readout. Date/Time used in the CMe/CMi Series products can be configured with UTC offset to set any time zone.

Value-data-count property

The value-data-count property is used to distinguish value data read from one telegram to another. The CMe/CMi Series products implement automatic FCB-bit toggling, which means that the product will automatically read all available data telegrams from a meter. A value of 0 means the value was found in telegram 0, a value of 1 means that the value was found in telegram 1.

Description property

This property describes the type of a value. A type can be i.e. energy, power, flow temperature etc. Description can be one or a combination of names. The description can also be a custom specified string describing the value, which can contain any character string.

All spaces in description names are replaced with character – (hyphen). Combination of description names are separated with space character. This helps finding the primary description of the value, i.e. the first word in the description name.

Descriptions listed in the following table are taken from the M-Bus standard EN13757.

Table 138. Standard description property values

Name

energy

volume

mass

on-time

op-time

power

volume-flow

volume-flow-ext

mass-flow

flow-temp

return-temp

diff-temp

ext-temp

pressure

date

datetime

units-for-HCA

avg-duration

act-duration

fabrication-no

enhanced-id

address

reactive-energy

cold/warm-temp-limit

cum-cnt-max-power

credit

debit

access-number

device-type

manufacturer

parameter-set-id

model/version

hw-version

fw-version

other-sw-version

customer-location

Customer

access-code-user

access-code-operator

access-code-system-operator

access-code-developer

password

error-flags-dev-spec

error-mask

digital-output

digital-input

baudrate

response-delay-time

retry

remote-control-dev-spec

first-storage-for-cyclic-storage

last-storage-for-cyclic-storage

size-of-storage-block

storage-interval

time-point

duration-since-last-readout

start-of-tariff

duration-of-tariff

period-of-tariff

dimensionless

Voltage

Current

reset-counter

cum-counter

control-signal

day-of-week

week-number

time-point-of-day-change

state-of-param-activation

special-supplier-information

duration-since-last-cum

operation-time-battery

datetime-of-battery-change

day-light-saving

listening-window-management

cold/warm-temp-limit

remaining-battery-lifetime

count-meter-stop

Reserved

manufacturer-specific

no-error

too-many-DIFE

storage-number-not-impl

unit-number-not-impl

tariff-number-not-impl

function-not-impl

data-class-not-impl

data-size-not-impl

too-many-VIFE

illegal-VIF-group

illegal-VIF-exponent

VIF/DIF-mismatch

unimpl-action

no-data-available

data-overflow

data-underflow

data-error

premature-end-of-record

inc-per-input-pulse-on-input-channel-0

inc-per-input-pulse-on-input-channel-1

inc-per-output-pulse-on-input-channel-0

inc-per-output-pulse-on-input-channel-1

start-date/time-of

uncorrected-unit

acc-only-if-pos-contr

acc-of-abs-value-only-if-neg-contr

lower-limit-value

exceeds-lower-limit-value

datetime-of-begin-of-first-lower-limit-exceeded

datetime-of-end-of-first-lower-limit-exceeded

datetime-of-begin-of-last-lower-limit-exceeded

datetime-of-end-of-last-lower-limit-exceeded

upper-limit-value

exceeds-of-upper-limit-value

datetime-of-begin-of-first-upper-limit-exceeded

datetime-of-end-of-first-upper-limit-exceeded

datetime-of-begin-of-last-upper-limit-exceeded

datetime-of-end-of-last-upper-limit-exceeded

duration-of-first-lower-limit-exceeded

duration-of-last-lower-limit-exceeded

duration-of-first-upper-limit-exceeded

duration-of-last-upper-limit-exceeded

duration-of-lower-limit-exceeded

duration-of-upper-limit-exceeded

value-during-lower-limit-exceeded

leak-values

datetime-of-first-begin

datetime-of-first-end

value-during-upper-limit-exceeded

overflow-values

datetime-of-last-begin

datetime-of-last-end

future-value


Unit property

This property describes the unit of a value. A unit can be i.e. Wh, kWh, °C etc. Units can be one or a combination of the names as listed in the following table. The unit can also be a custom specified string describing the value, which can contain any character string.

All spaces in description names are replaced with character – (hyphen). Combination of units names are separated with space or slash (/) character. This helps finding the primary unit of the value, i.e. the first word in the unit name.

Units listed in the following table are taken from the M-Bus standard EN13757.

Table 139. Standard unit property values

Unit

Wh

J

m3

Kg

second(s)

minute(s)

hour(s)

day(s)

W

m3/h

m3/m

m3/sec

kg/h

°C

K

Bar

MWh

kVARh

GJ

Ton

feet^3

USgallon

USgallon/min

USgallon/h

MW

GJ/h

°F

local-curreny-unit(s)

Baud

Bittimes

month(s)

year(s)

V

A

reserved

/s

/min

/h

/day

/week

/month

/year

/revol/measurem

/liter

/m3

/kg

/K

/kWh

/GJ

/kW

/k*liter

/V

/A

*s

*s/V

*s/A

*s/A


Function property

This property describes the function of a value. A function can be i.e. minimum value, maximum value etc.

Functions listed in the following table are taken from the M-Bus standard EN13757.

Table 140. Standard function property values

Name

Description

inst-value

The value is an instantaneous value (Current value)

max-value

The value is a maximum value at a specific date/time

min-value

The value is a minimum value at a specific date/time

err-value

The value contains error and should not be treated as qualified value.


Tariff property

Tariff property is a numeric value describing the tariff of a value.

Sub-unit property

Sub-unit property is a numeric value describing the sub-unit of a value. Sub-unit is often used to distinguish almost identical values, for example a software version from a meter can be of sub-unit 0 and software version of the M-Bus module used to communicate with the meter can be of sub-unit 1.

Storage-number property

Storage-number property is a numeric value describing the storage-number of a value. Storage-number is normally used to identify a load profile or other historical value.

Identifying the properties and using correct meter values

Depending on meter used, a wide range of data can be available. A standard electricity meter normally provides numerous of extra information besides e.g. energy and power.

This section describes how to find and identify commonly used information from standard M-Bus meters. Please note that depending on meter, this information may vary.

Meters

Electricity meters

Table 141. Commonly used properties for electricity meters

Value of interest

Description

Unit

Function

Tariff

Sub-unit

Storage number

Current energy meter stand

energy

Wh

inst-value

0

0

0

Current power

power

W

inst-value

0

0

0

Current energy meter stand – Tariff 1

energy

Wh

inst-value

1

0

0

Maximum power

power

W

max-value

0

0

0


Water meters

Table 142. Commonly used properties for water meters

Value of interest

Description

Unit

Function

Tariff

Sub-unit

Storage number

Current volume meter stand

volume

m3

inst-value

0

0

0


District heat and cold meters

Table 143. Commonly used properties for district heat and cold meters

Value of interest

Description

Unit

Function

Tariff

Sub-unit

Storage number

Current volume meter stand

energy

Wh

inst-value

0

0

0

Current volume meter stand

volume

m3

inst-value

0

0

0

Current power

power

W

inst-value

0

0

0

Current forward temperature

flow-temp

°C

inst-value

0

0

0

Current backward temperature

return-temp

°C

inst-value

0

0

0

Current temperature difference

diff-temp

K

inst-value

0

0

0

Current volume flow

volume-flow

m3/h

inst-value

0

0

0


Gas meters

Table 144. Commonly used properties for gas meters

Value of interest

Description

Unit

Function

Tariff

Sub-unit

Storage number

Current volume meter stand

volume

m3

inst-value

0

0

0

Current volume flow

volume-flow

m3/h

inst-value

0

0

0


Was this article helpful?

0 out of 0 found this helpful
Have more questions? Submit a request

Comments (0 comments)

Article is closed for comments.