Microtronics myDatalogEASY IoTmini User Manual

User manual
myDatalogEASY IoTmini
Cover
Valid from:
Firmware version: 01v015
l Server version: 47.10
l Hardware version: 1.0
l
301115 | Rev.01
Chapter 1 Table of contents
Chapter 1 Table of contents
Cover
1
Chapter 1 Table of contents
3
Chapter 2 Declaration of conformity
11
Chapter 3 Specifications
13
Chapter 4 General specifications
17
4.1 Translation
17
4.2 Copyright
17
4.3 General descriptive names
17
4.4 Safety instructions
17
4.4.1 Use of the hazard warnings
18
4.4.2 General safety instructions
18
4.4.3 Safety and preventative measures for handling wireless modules
19
4.4.3.1 Safety and precautionary measures for the wireless module installation
19
4.4.3.2 Safety measures for installing the antenna
19
4.5 Overview
4.5.1 Block diagram
20
21
4.6 Intended use
22
4.7 General product information
22
4.8 Device labelling
23
4.9 Installation of spare and wear parts
24
4.10 Storage of the product
24
4.11 Warranty
24
4.12 Disclaimer
25
4.13 Obligation of the operator
25
4.14 Personnel requirements
26
Chapter 5 Functional principle
27
5.1 Recommended procedure
29
5.1.1 Development of M2M/IoT application
29
5.2 Functionality of the internal data memory
29
5.3 Memory organisation
31
5.4 Error handling
32
Rev. 01
3
5.5 Registration memory blocks
32
5.5.1 REG_SYS_FLASH
33
5.5.2 REG_APP_OTP
33
Chapter 6 Storage, delivery and transport
6.1 Inspection of incoming deliveries
35
6.2 Scope of supply
35
6.3 Storage
36
6.4 Transport
36
6.4.1 Transporting power supply units
6.5 Return
Chapter 7 Installation
36
38
39
7.1 Dimensions
39
7.2 Assembling the myDatalogEASY IoTmini
39
7.3 Installing the myDatalogEASY IoTmini
45
7.3.1 Wall mounting
46
7.3.2 Top-hat rail assembly
47
7.3.3 Pipe assembly
48
7.4 Safety instructions for the cabling
7.4.1 Information on preventing electrostatic discharges (ESD)
7.5 Electrical installation
7.5.1 Connecting the sensors, actuators and power supply
4
35
49
50
50
50
7.5.1.1 Connection examples
54
7.5.2 Connecting the LoRa antenna
54
7.5.3 Technical details about the universal inputs
55
7.5.3.1 0/4 to 20mA mode
55
7.5.3.2 0 to 2V mode
55
7.5.3.3 0 to 10V mode
55
7.5.3.4 Standard digital modes (PWM, frequency, digital, counter)
56
7.5.4 Technical details about the PT100/1000 interface
56
7.5.5 Technical details about the RS485 interface
56
7.5.6 Technical details about the RS232 interface
57
7.5.7 Technical details about the USB interface
58
7.5.8 Technical details about the outputs
59
Rev. 01
Chapter 1 Table of contents
7.5.8.1 Switchable sensor supply VOUT
59
7.5.8.2 Switchable sensor supply VEXT
60
7.5.8.3 Switchable sensor supply VEXTRS232
61
7.5.8.4 Isolated switch contact (NO, CC)
61
7.5.9 Technical details about energy management
61
7.5.10 Technical details about the energy supply
62
7.5.10.1 PSU413D+ AP (300524)
63
7.5.10.2 PSU413D AP (300525)
63
7.5.10.3 PSU713 BP (300526)
64
7.5.10.4 PSU DC (300529)
64
7.5.10.5 PSU AC (300558)
64
7.5.10.6 PSU DC+ (300798)
65
7.5.11 Technical details about the system time
65
Chapter 8 Initial Start-Up
67
8.1 User information
67
8.2 Applicable documents
67
8.3 General principles
67
8.4 Commissioning the system
67
8.5 Testing communication with the device
69
Chapter 9 User interfaces
9.1 User interface on the myDatalogEASY IoTmini
71
71
9.1.1 Operating elements
71
9.1.1.1 Solenoid switch
71
9.1.1.2 Two-colour LED
71
9.2 User interface on the myDatanet server
9.2.1 Site configuration
Rev. 01
72
72
9.2.1.1 Site
72
9.2.1.2 Comments
72
9.2.1.3 Control
73
9.2.1.4 Configuration 0 - Configuration 9
73
9.2.1.5 Alarm settings
74
9.2.1.6 Basic settings
75
9.2.1.7 FTP export settings
75
5
9.2.2 Device configuration
9.2.2.1 Comments
76
9.2.2.2 Measurement instrument
76
Chapter 10 rapidM2M Studio
79
10.1 General
79
10.2 Prerequisites
80
Chapter 11 myDatanet server
81
11.1 Recommended procedure
81
11.1.1 Creating the site
Chapter 12 Device Logic (Pawn)
12.1 General
81
83
83
12.1.1 Direct entry of a device logic
83
12.1.2 Uploading a binary file
83
12.1.3 Using the CODEbed of the web-based development environment rapidM2M Studio
83
12.2 Compiler options
84
12.3 rapidM2M Device API
84
12.3.1 Constants
84
12.3.2 Timer, date & time
85
12.3.2.1 Arrays with symbolic indices
85
12.3.2.2 Constants
85
12.3.2.3 Functions
85
12.3.3 Uplink
90
12.3.3.1 Constants
90
12.3.3.2 Callback functions
90
12.3.3.3 Functions
91
12.3.4 System
95
12.3.4.1 Arrays with symbolic indices
95
12.3.4.2 Constants
95
12.3.4.3 Functions
97
12.3.5 Encoding
6
76
99
12.3.5.1 Constants
99
12.3.5.2 Functions
100
12.3.6 RS232, RS485
105
Rev. 01
Chapter 1 Table of contents
12.3.6.1 Constants
105
12.3.6.2 Callback functions
105
12.3.6.3 Functions
107
12.3.7 LoRa
113
12.3.7.1 Constants
113
12.3.7.2 Callback functions
113
12.3.7.3 Functions
114
12.3.8 Registry
117
12.3.8.1 Constants
117
12.3.8.2 Callback functions
118
12.3.8.3 Functions
118
12.3.9 Position
122
12.3.9.1 Arrays with symbolic indices
122
12.3.9.2 Constants
122
12.3.9.3 Functions
124
12.3.10 Math
128
12.3.11 Char & String
131
12.3.12 CRC & hash
136
12.3.12.1 Arrays with symbolic indices
136
12.3.12.2 Functions
136
12.3.13 Various
137
12.3.13.1 Arrays with symbolic indices
137
12.3.13.2 Constants
138
12.3.13.3 Functions
138
12.3.14 Console
144
12.3.15 Universal inputs
145
12.3.15.1 Constants
145
12.3.15.2 Functions
146
12.3.16 Outputs
12.3.16.1 Constants
149
12.3.16.2 Functions
149
12.3.17 LED
12.3.17.1 Constants
Rev. 01
149
154
154
7
12.3.17.2 Functions
155
12.3.18 Solenoid switch
157
12.3.18.1 Constants
157
12.3.18.2 Callback Funktionen
157
12.3.18.3 Functions
158
12.3.19 Power management
12.3.19.1 Arrays with symbolic indices
159
12.3.19.2 Constants
159
12.3.19.3 Callback functions
160
12.3.19.4 Functions
160
12.4 Device Logic error codes
161
12.5 Syntax
164
12.5.1 General syntax
164
12.5.1.1 Format
164
12.5.1.2 Optional semicolons
164
12.5.1.3 Comments
164
12.5.1.4 Identifier
164
12.5.1.5 Reserved keywords
164
12.5.1.6 Numerical constants
165
12.5.1.6.1 Numerical integer constants
165
12.5.1.6.2 Numerical floating-point constants
165
12.5.2 Variables
8
159
165
12.5.2.1 Declaration
165
12.5.2.2 Local declaration
165
12.5.2.3 Global declaration
165
12.5.2.4 Static local declaration
166
12.5.2.5 Static global declaration
166
12.5.2.6 Floating point values
166
12.5.3 Constant variables
166
12.5.4 Array variables
166
12.5.4.1 One-dimensional arrays
166
12.5.4.2 Initialisation
167
12.5.4.3 Progressive initialisation for arrays
167
Rev. 01
Chapter 1 Table of contents
12.5.4.4 Multi-dimensional arrays
167
12.5.4.5 Arrays and the "sizeof" operator
168
12.5.5 Operators and expressions
169
12.5.5.1 Notational conventions
169
12.5.5.2 Expressions
169
12.5.5.3 Arithmetic
169
12.5.5.4 Bit manipulation
170
12.5.5.5 Assignment
170
12.5.5.6 Comparative operators
171
12.5.5.7 Boolean
171
12.5.5.8 Other
172
12.5.5.9 Priority of the operators
172
12.5.6 Statements
12.5.6.1 Statement label
173
12.5.6.2 Composite statements
174
12.5.6.3 Expression statement
174
12.5.6.4 Empty statement
174
12.5.6.5 Assert expression
174
12.5.6.6 Break
175
12.5.6.7 Continue
175
12.5.6.8 Do statement while (expression)
176
12.5.6.9 Exit expression
176
12.5.6.10 For (expression 1; expression 2; expression 3) statement
176
12.5.6.11 Goto label
177
12.5.6.12 If (expression) statement 1 else statement 2
177
12.5.6.13 Return expression
177
12.5.6.14 switch (expression) {case list}
177
12.5.6.15 While (expression) statement
178
12.5.7 Functions
179
12.5.7.1 Function arguments ("call-by-value" versus "call-by-reference")
179
12.5.7.2 Named parameters versus fixed parameters
181
12.5.7.3 Standard values of function arguments
181
12.6 Differences to C
Rev. 01
173
182
9
Chapter 13 Data Descriptor
185
Chapter 14 API
187
14.1 Frontend API
187
14.2 rapidM2M Playground
187
14.2.1 Overview
188
Chapter 15 Maintenance
189
15.1 General maintenance
189
15.2 Replacing the power supply unit
189
15.2.1 Charging the power supply unit
15.3 Power supply units with integrated energy store
193
Chapter 16 Removal/disposal
195
Chapter 17 Troubleshooting and repair
197
17.1 General problems
197
17.2 Log entries and error codes
199
17.3 Evaluating the device log
201
17.3.1 Evaluating the device log on the myDatanet server
201
17.3.2 Evaluating the device log using DeviceConfig
201
Chapter 18 Spare parts and accessories
10
191
203
18.1 Chargeable features
203
18.2 Assembly sets
203
18.3 Antennas
203
18.4 Power supply units
204
18.5 Charging devices and power supply units
204
18.6 Other accessories
204
Chapter 19 Document history
205
Chapter 20 Glossary
207
Chapter 21 Contact information
209
Rev. 01
Chapter 2 Declaration of conformity
Chapter 2 Declaration of conformity
Rev. 01
11
Chapter 3 Specifications
Chapter 3 Specifications
Voltage
supply
Rechargeable battery:
l PSU413D+ AP : 13,6Ah, Li-Ion , integrated overvoltage protection
l PSU413D AP : 13,2Ah, Li-Ion , integrated overvoltage protection
Battery:
l PSU713 BP : 13Ah
Direct power supply:
l PSU DC : DC protective circuit
l PSU DC+ : 900mAh, Li-Po , DC protective circuit
l PSU AC : 900mAh, Li-Po , 230VAC power supply unit
Additional information is provided in "Technical details about the energy supply" on page 62.
Supply or
charging
voltage
12...32VDC (max. 12W )
Housing
Material:
Weight:
Degree of protection:
Dimensions (WHD):
Operating
temperature
-20...+60°C
Air humidity
15...90%rH non-condensing
Storage
temperature
-30...+85°C
Display
Two-colour LED with selectable function:
l Signalling the operating state (controlled by the FW)
l Function freely useable (controlled by the device logic)
Operation
Solenoid switch with selectable function:
l Initiation of the transmission (evaluated by the FW)
l Function freely useable (evaluated by the device logic)
Antenna
connector
FME-M
Rev. 01
ABS / PC (housing/cover)
330g (without power supply unit)
IP66
86 x 175 x 64mm (without antenna)
13
Universal
inputs 1)
4 x analogue or digital
Modes:
l 0/4...20mA: Resolution 6,3µA, max. 23,96mA, load 96Ω
l 0...2V: Resolution 610µV, max. 2,5V, load 10k086
l 0...10V: Resolution 7,97mV, max. 32V, load 4k7
l PWM: 1...99%, max. 100Hz, min. pulse length 1ms, load 10k086
l Frequency: 1...1000Hz, 10k086
l Digital: max. 32V, low <0,99V, high >2,31V, load 10k086
l Counter: min. pulse length 1ms, load 10k086
Additional information is provided in "Technical details about the universal inputs" on page
55.
System time
Hardware real-time clock with its own buffer battery (service life >10 years) and automatic
time synchronisation with the server
Additional information is provided in "Technical details about the system time" on page 65.
Internal
sensors
Internal housing temperature
l Measurement range: -20...+60°C
l Resolution: 0,1°C
Humidity in the housing
l Measurement range: 0...100% rH
l Resolution: 0,1% rH
External
temperature
sensor 2)
1 x PT100/1000 (including auto detection)
Serial
interface
1 x RS232 (4-wire) 3)
l Baud rate: 600-115200
l Stop bits: 1, 2
l Parity: N, E, O
l Data bits: 7, 8
l Flow control: Off, RTS/CTS
Additional information is provided in "Technical details about the PT100/1000 interface" on
page 56.
1 x RS485 (2-wire) 4) 5)
l Baud rate: 600-115200
l Stop bits: 1, 2
l Parity: N, E, O
l Data bits: 7, 8
l Load resistance: Off, 120Ω
Additional information is provided in "Technical details about the RS485 interface" on page
56 and "Technical details about the RS232 interface" on page 57.
14
Rev. 01
Chapter 3 Specifications
Outputs
2 x switchable 3,3V supply (max. 180mA )
1 x switchable and adjustable sensor supply
The device logic can be used to vary the output voltages in the range of 5...24V .
l
5Vnominal: 4,75V at Iout = 50mA
l 12V
: 11,7V at Iout = 50mA
nominal
l 15V
: 14,7V at Iout = 50mA
nominal
l 24V
: 23,4V at Iout = 50mA
nominal
1x isolated switch contact:
l I
: 130mA
max
l U
: 32V
max
l R
: 35Ω
on
l f
: 1000Hz
max
Modes:
l Digital
l Frequency: Adjustment range 1...1000Hz, pulse duty factor 1...100%
l PWM: Adjustment range 0...100%, frequency 0...1000Hz
l Pulse: Pulse duration 1...500ms , pulse pause 1...500ms
l Pulse/min
Additional information is provided in "Technical details about the outputs" on page 59.
Bluetooth 6)
5.0 compatible low energy module
LoRa 7)
Sub-GHz LoRa transceiver module
USB
interface
1 x mini-B USB 2.0 slave for the connection to a PC. The DeviceConfig configuration
program must be installed on the PC or the web-based development environment rapidM2M
Studio must be used to enable communication with the myDatalogEASY IoTmini .
Additional information is provided in "Technical details about the USB interface" on page 58.
Data memory 3MB internal flash memory.
The size of the data records is variable (max. 1024 Byte ) and is determined by the device
logic created by the user. The system-related overhead is 10 Byte per data record.
Additional information is provided in"Functionality of the internal data memory" on page 29.
Configuration 10 independent blocks each with 4000 Byte
memory
Registration
memory
Flash: 4 blocks each with 1kB and pre-defined purposes for storing device-specific data
RAM: 1 optional block with max. 1kB for storing application-specific data
Additional information is provided in "Registration memory blocks" on page 32.
Rev. 01
15
Memory for
the PAWN
binary
256kB (uncompressed size)
Additional information is provided in "Memory organisation" on page 31.
Data
Bluetooth Low Energy: 6)
transmission Range: 20m (depending on the environmental conditions)
LoRa: 7)
Supported frequencies:868MHz, 915MHz
1) The universal inputs 3 and 4 are only available if the RS485 interface is not used.
2) In order for the external temperature sensor to be used, the chargeable feature "Activation code temperature
input(300542)" must be unlocked or order option "Feature activation temperature input (300732)" is required.
3) In order for the RS232 interface to be used, the chargeable feature "Activation code RS232 (300541)" must be unlocked
or order option "Feature activation RS232 (300731)" is required.
4) In order for the RS485 interface to be used, the chargeable feature "Activation code RS485 (300540)" must be unlocked
or order option "Feature activation RS485 (300730)" is required.
5) The RS485 interface is only available if the universal inputs 3 and 4 are not being used.
6) In order for the Bluetooth module to be used, the chargeable feature "Activation code BLE (300968)" must be unlocked
or order option "Feature activationg BLE (300972)" is required.
7) In order for the LoRa module to be used, the order option "Feature activation LoRa (300971)" is required.
16
Rev. 01
Chapter 4 General specifications
Chapter 4 General specifications
The information in this manual has been compiled with great care and to the best of our knowledge. The
manufacturer, however, assumes no liability for any incorrect specifications that may be provided in this
manual. The manufacturer is not responsible for direct, indirect, accidental or consequential damages which
arise from errors or omissions in this manual even if advised of the possibility of such damages. In the interest
of continuous product development, the manufacturer reserves the right to make improvements to this
manual and the products described in it at any time and without prior notification or obligation.
Note: The specifications in this manual are valid as of the versions listed on the front page. Revised versions
of this manual, as well as software and driver updates are available in the service area of the myDatanet
server.
4.1 Translation
For deliveries to countries in the European Economic Area, the manual must be translated into the language
of the respective country. If there are any discrepancies in the translated text, the original manual (German)
must be referenced or the manufacturer contacted for clarification.
4.2 Copyright
The copying and distribution of this document as well as the utilisation and communication of its contents to
others without express authorisation is prohibited. Contraventions are liable to compensation. All rights
reserved.
4.3 General descriptive names
The use of general descriptive names, trade names, trademarks and the like in this manual does not entitle
the reader to assume they may be used freely by everyone. They are often protected registered trademarks
even if not marked as such.
4.4 Safety instructions
For the connection, commissioning and operation of the myDatalogEASY IoTmini , the following information
and higher legal regulations of the country (e.g. ÖVE), such as valid EX regulations as well as the applicable
safety and accident prevention regulations for the respective application case must be observed.
Read this manual completely before unpacking, setting up or operating this device. Observe all hazard,
danger and warning information. Non-observance can lead to serious injuries to the operator and/or damage
to the device.
Ensure that the safety equipment of this measurement instrument is not impaired. Install and use the
measurement system only in the manner and method described in this manual.
Rev. 01
17
Important note: The manufacturer's products that are designed for outdoor use include extensive
protection against moisture and dust penetration. If these products are connected to the power supply
or sensors by cables with connectors rather than permanently installed cables, the susceptibility of the
connector and socket to moisture and dust penetration is significantly higher. The operator is
responsible for protecting the connector and socket against penetrating moisture and dust in a
suitable way and complying with local safety regulations.
4.4.1 Use of the hazard warnings
DANGER:
Indicates a potential or threatening hazardous situation that will result in death or serious
injuries if not avoided.
WARNING:
Indicates a potential or threatening hazardous situation that can result in death or serious
injuries if not avoided.
CAUTION:
Indicates a potential hazardous situation that can result in minor or moderate injuries or
damage to this instrument.
Important note: Indicates a situation that can result in damages to this instrument if it is not avoided.
Information that must be particularly emphasised.
Note: Indicates a situation that does not result in any injury to persons.
Note: Information that supplements the specifications in the main text.
4.4.2 General safety instructions
WARNING:
Hazardous electric voltage can cause electric shock or burns. Always switch off all of the
used power supplies for the device before installing it, completing any maintenance work
or resolving any faults.
WARNING:
Ensure that the device is fully deactivated and cannot activate automatically when
sending/returning it as air freight. Information on this is provided in chapter "Storage of
the product" on page 24. If you have any unanswered questions, contact the manufacturer
(see "Contact information" on page 209).
WARNING:
Never use this device in areas where the use of wireless equipment is prohibited. The
device must not be used in hospitals and/or in the vicinity of medical equipment, such as
heart pacemakers or hearing aids, as their functionality could be compromised by the
wireless modulecontained in the device.
WARNING:
Never use this device in potentially explosive atmospheres and in the vicinity of highly
combustible areas (fuel stations, storage areas for combustible material, chemical plants
and detonation sites) or in the vicinity of flammable gases, vapours or dust.
18
Rev. 01
Chapter 4 General specifications
4.4.3 Safety and preventative measures for handling wireless modules
The following safety and preventative measures must be observed during all phases of installation, operation,
maintenance or repair of a wireless module. The manufacturer is not liable if the customer disregards these
preventative measures.
CAUTION:
The wireless connection must not be used in hazardous environments.
No guarantee of any kind, whether implicit or explicit, is given by the manufacturer and its suppliers for the use
with high risk activities.
In addition to the following safety considerations, all directives of the country in which the device is installed
must be complied with.
4.4.3.1 Safety and precautionary measures for the wireless module installation
This device must only be installed by a trained technician who applies the recognised installation
practices for a radio frequency transmitter including the correct grounding of external antennas.
l The device must not be operated in hospitals and/or in the vicinity of medical equipment such as heart
pacemakers or hearing aids.
l The device must not be operated in highly flammable areas such as petrol filling stations, fuel storage
sites, chemical factories and explosion sites.
l The device must not be operated in the vicinity of flammable gases, vapours or dusts.
l The device must not be subjected to strong vibrations or impacts.
l The wireless module can cause interferences if it is located in the vicinity of television sets, radios or
computers.
l Do not open the wireless module. Any modification to the device is prohibited and will result in the
operating licence being revoked.
l Do not install the device in any other way to the one described in the operating instructions. Improper
use will invalidate the warranty.
l
4.4.3.2 Safety measures for installing the antenna
Only use antennas that are recommended or supplied by the manufacturer.
The antenna must be installed at a distance of at least 20 cm from individuals.
l The antenna must not be extended outside protected buildings and must be protected against lightning
strikes.
l The voltage supply must be switched off before replacing the antenna.
l
l
Rev. 01
19
4.5 Overview
Note: As the myDatalogEASY IoTmini is split into several components when delivered, it must be
assembled before use (see "Assembling the myDatalogEASY IoTmini " on page 39).
Front of the myDatalogEASY IoTmini
(view of a device after assembly)
Rear of the myDatalogEASY IoTmini
(view of a device after assembly)
1 Antenna connector
3 Cable screw connection (cable diameter of 510 mm)
2 Housing cover
4 Pressure compensation
20
Rev. 01
Chapter 4 General specifications
4.5.1 Block diagram
Block diagram of the myDatalogEASY IoTmini
1) It is a DC/DC converter with controllable output current. A power supply unit (e.g. PSU413D+ AP ) that is equipped with a
rechargeable battery can thus be charged via the V
in-/output.
Batt
Rev. 01
21
Note: Detailed block diagrams of the most common power supply units are provided in
chapter "Technical details about the energy supply" on page 62.
4.6 Intended use
The portable, freely programmable measurement instrument is designed for determining, processing and
transferring measurement data acquired via various industrial interfaces. The device can operate without
mains power. The measured and recorded data is stored on a non-volatile memory medium. The stored data
can be sent to a central server via LoRaWAN for further processing. The maximum permissible limit values
specified in chapter "Specifications" on page 13 must be observed. The manufacturer shall not be liable for
any operational cases that deviate from these limit values and have not been approved by the manufacturer in
writing.
Note: This device is exclusively intended to be used for the purposes as described before. Any other
use or use beyond what is specified or a modification of the device shall be deemed to be not for the
intended purpose and is not permitted without the express written consent of the manufacturer. The
manufacturer shall not be held liable for any damages that may result from such unauthorised use or
modification. The operator alone bears the associated risk.
Note: The manufacturer is not liable for data loss of any kind.
4.7 General product information
The device is a compact, freely programmable device for determining, processing and transferring
measurement data.
The following interfaces are available for recording measurement data:
4 universal inputs that can be operated in various analogue and digital modes. 1)
l An interface for connecting a PT100 or PT1000 including automatic detection of which type is being
used 2)
3)
l One RS232 interface
1) 4)
l One RS485 interface
l
The myDatalogEASY IoTmini is also equipped with internal sensors (internal housing temperature and air
humidity in the housing), 3 switchable voltage outputs to supply the sensors and an isolated switch contact to
directly control an actuator. For one of the switchable sensor supplies the device logic can be used to vary the
output voltage (see "Vsens_On()") in the range of 5...24V . The output voltage for the other 2 switchable
sensor supplies is 3,3V and cannot be changed. The isolated switch contact can be operated in different
modes (digital, frequency, PWM, pulse, pulse/min.).
The customer can create their own application via the rapidM2M Studio (see "rapidM2M Studio " on page
79). During development the part of the application that needs to be installed on the device (i.e. the device
logic) is loaded into the myDatalogEASY IoTmini via the USB interface. For applications that are provided via
the rapidM2M Store installation of the device logic is performed via the USB connection in the course of
connecting the site with the myDatalogEASY IoTmini . The device logic enables access to the serial
interfaces (RS232 3) and RS485 3)) thus providing the customer with the option to connect to almost all of the
devices and sensors that are compatible with these interfaces and to implement the corresponding
communication protocols.
The myDatalogEASY IoTmini provides the customer with a memory area for their data (3MB ) as well as 10
independent memory blocks each with 4000 Byte for the configuration data. In addition to the 4 registration
memory blocks each with 1kB , that are saved in the flash, the myDatalogEASY IoTmini has another one that
22
Rev. 01
Chapter 4 General specifications
can optionally be initialised via the "rM2M_RegInit()" function and that is saved in the RAM. Its size can be
specified during initialisation, although it is limited to a maximum of 1kB . The registration memory blocks are
assigned to predefined purposes and are designed for storing device-specific data (see "Registration
memory blocks" on page 32).
Recorded measurement data can be sent to a central myDatanet server via LoRaWAN5) for further
processing.
Synchronisation of the configuration and registration data with the server, however, is only possible via the
USB connection .
1) The universal inputs 3 and 4 are only available if the RS485 interface is not used.
2) In order for the external temperature sensor to be used, the chargeable feature "Activation code temperature
input(300542)" must be unlocked or order option "Feature activation temperature input (300732)" is required.
3) In order for the RS232 interface to be used, the chargeable feature "Activation code RS232 (300541)" must be unlocked
or order option "Feature activation RS232 (300731)" is required.
4) In order for the RS485 interface to be used, the chargeable feature "Activation code RS485 (300540)" must be unlocked
or order option "Feature activation RS485 (300730)" is required.
5) In order to transfer the data via LoRaWANthe order option "Feature activation LoRa (300971)" is required.
4.8 Device labelling
The specifications in this user manual apply exclusively to the myDatalogEASY IoTmini device type. The type
plates are located on the right side of the device and contain the following specifications:
Type designation
Item number
1)
l DevEUI of the LoRA module
l Specification of the product range
l Serial number
l Environmental conditions during operation
l Protection class
l Hardware revision
l CE marking
l Logo for the EU WEEE Directive
l
l
1) Only in the case of order option "Feature activation LoRa (300971)"
The correct specification of the type designation and serial number is important for all queries and spare part
orders. Only then can we process requests promptly and properly.
Type plates myDatalogEASY IoTmini
Rev. 01
23
Note: These operating instructions are part of the device and must be available to the user at all
times. The safety instructions contained therein must be observed.
WARNING:
It is strictly prohibited to disable the safety equipment or modify its mode of operation.
4.9 Installation of spare and wear parts
Be advised that spare and accessory parts that have not been supplied by the manufacturer have also not
been inspected or approved by the manufacturer. The installation and/or use of such products can possibly
have a negative impact on the specified constructional properties of the device. The manufacturer shall not be
liable for any damages that arise from the use of non-original parts and non-original accessory parts.
4.10 Storage of the product
For safekeeping of the myDatalogEASY IoTmini , ensure that all relevant data was transferred to the
myDatanet server. If necessary, initiate a transmission directly on the device using the solenoid contact (see
"Solenoid switch" on page 71), if you have included this in your Device Logic, and then check again to see
whether all of the relevant data has now been transferred. If your device does not include the option to initiate
the transmission of temporarily stored measurement data, you may have to wait until the next scheduled data
transmission for all of the data to be sent to the myDatanet server. Remove the power supply unit before
disconnecting the cables and antenna. If possible, switch off the supply or charging voltage before
disconnecting the cables from the V IN and GND clamps (see "Connecting the sensors, actuators and power
supply" on page 50). Store the myDatalogEASY IoTmini and power supply unit in the original packaging.
The configuration and most recently determined data are retained. The system time also continues to run
thanks to the hardware real-time clock equipped with its own buffer battery. This means that a valid time basis
is available immediately following recommissioning (see "Technical details about the system time" on page
65).
4.11 Warranty
The device has been functionally tested before delivery. If it is used as intended (see "Intended use" on page
22) and the operating instructions, the applicable documents (see "Applicable documents " on page 67) and
the safety notes and instructions contained therein, are observed, no functional restrictions are to be
expected and perfect operation should be possible.
Note: Please also note in this regard the next chapter "Disclaimer" on page 25.
Note: Limitation of warranty
In the event of non-compliance with the safety instructions and instructions in this document, the
manufacturer reserves the right to limit the warranty.
24
Rev. 01
Chapter 4 General specifications
4.12 Disclaimer
The manufacturer assumes no liability
l
l
l
l
l
l
l
for damages owing to a change of this document. The manufacturer reserves the right to change the
contents of this document and this disclaimer at any time and without any notice.
for damages to persons or objects resulting from failure to comply with applicable regulations. For
connection, commissioning and operation of the devices/sensors all available information and higher
local legal regulations (e.g. in Austria ÖVE guidelines) such as applicable Ex regulations as well as
safety requirements and regulations in order to avoid accidents shall be adhered to.
for damages to persons or objects resulting from improper use. For safety and warranty reasons, all
internal work on the instruments beyond from that involved in normal installation and connection, must
be carried out only by qualified Microtronics personnel or persons or companies authorised by
Microtronics .
for damages to persons or objects resulting from the use of instruments in technically imperfect
condition.
for damages to persons or objects resulting from the use of instruments not in accordance with the
requirements.
for damages to persons or objects resulting from failure to comply with safety information
contained within this instruction manual.
for missing or incorrect measurement values or resulting consequential damages due to improper
installation.
4.13 Obligation of the operator
WARNING:
In the EEA (European Economic Area), the national implementation of the framework
directive (89/391/EEC) as well as the associated specific directives and from these in
particular, the directive (2009/104/EC) about the minimum safety and health requirements
for use of work equipment by workers at work, each in their respective version are to be
complied with.
The operator must obtain the local operating licence and the associated documents.
In addition, the operator must comply with the local legal requirements for
the safety of the personnel (accident prevention measures),
the safety of the equipment (protective equipment and maintenance),
l the product disposal (waste disposal law),
l the material disposal (waste disposal law),
l the cleaning (cleaning agents and disposal) and
l the environmental protection amendments.
l
l
Before commissioning, the operator must ensure that the installation and commissioning – provided these
were performed by the operator himself – are in compliance with the local regulations.
Rev. 01
25
4.14 Personnel requirements
Installation, commissioning and maintenance may only be completed by personnel who meet the following
conditions:
l
l
Qualified specialist personnel with the relevant training
Authorised by the facility operator
Note: Qualified personnel
In the context of these instructions and the warnings on the product itself, individuals responsible for the setup,
installation, commissioning and operation of the product must have gained relevant qualifications relating to
their activities, including, for example:
l
l
l
26
Training, instruction and authorisation to activate/deactivate, ground and label electric circuits and
devices/systems in accordance with the standards of safety engineering.
Training or instruction on the maintenance and use of suitable safety equipment in accordance with the
standards of safety engineering.
First aid training
Rev. 01
Chapter 5 Functional principle
Chapter 5 Functional principle
In the graphic below, all of the components that are part of the myDatanet are illustrated in grey. All other
components must be provided/created by the customer.
Functional principle
1 Client that uses a web browser to access the interface of the customer-specific server, which receives its
data by means of a LoRaWAN connection.
2 PC with the DeviceConfig configuration program installed
3 Client that accesses the interface of the myDatanet server via the web browser
4 Customer-specific server that provides clients with their own interface. The customer-specific server
receives the data by means of a LoRaWAN connection from the myDatalogEASY IoTmini .
5 myDatalogEASY IoTmini with integrated managed service SIM chip (including data transmission)
6 Application created by the customer (device logic) that collects and records the data (see"Device Logic
(Pawn)" on page 83)
7 myDatanet server to which the data is transferred
8 Data Descriptor defined by the customer that enables the use of the measurement data and
configurations generated by the application (device logic) in connection with the interface of the
myDatanet server (see "Data Descriptor " on page 185)
Rev. 01
27
9 Customer-specific server that provides clients with their own interface. The customer-specific server
obtains the data via the API interface of the myDatanet server (see "API" on page 187).
10 Client, on which a PC program is running, that obtains its data via the API interface of the myDatanet
server (see "API" on page 187)
11 Client that uses a web browser to access the interface of the customer-specific server, which receives its
data by means of the API interface of the myDatanet server.
As illustrated in the previous figure (see "Functional principle" on page 27), there are 2 options for transferring
the data from the myDatalogEASY IoTmini to the myDatanet server:
l
l
Directly via LoRaWAN
Indirectly, by initially reading the data from the device via the DeviceConfig configuration program using
the USB connection and then using the PC’s Internet connection to transfer the data to the server
For transferring the data from the myDatalogEASY IoTmini to the customer-specific server only one option is
available:
l
Directly via LoRaWAN
Functions and components provided by myDatanet :
l
myDatalogEASY IoTmini
Programmable (see "Device Logic (Pawn)" on page 83), portable device with integrated memory and
standardised industrial interfaces (UI1-4, PT100/1000, RS232, RS485, isolated switch contact) to
connect sensors and actuators to the myDatanet server (LoRaWAN) or customer-specific server
(LoRaWAN)
l
DeviceConfig configuration program (optional)
The DeviceConfig configuration program is required to read out the data from the
myDatalogEASY IoTmini via the USB connection and to forward it to a central myDatanet server. An
Internet connection is required for this purpose. The DeviceConfig configuration program uses
port 51241 to transfer data.
l
myDatanet server
Database for saving the measurement data and configurations. Data is either accessed via the API of
the server (see "API" on page 187) or web interface of the server.
Functions and components provided by the customer
l
Sensor and actuators
Sensors and actuators that have interfaces that are compatible with the specifications listed in the
chapter "Specifications" (see "Specifications" on page 13)
28
Rev. 01
Chapter 5 Functional principle
l
Application (device logic)
The firmware of the myDatalogEASY IoTmini only manages the synchronisation of the measurement
data and configurations between the myDatalogEASY IoTmini and myDatanet server. The application
created by the customer must record the measurement values and create the data blocks that are to be
saved. The data blocks, on the other hand, are stored by the firmware of the myDatalogEASY IoTmini
(see "rM2M_RecData()").
l
Data Descriptor
The basic function of the myDatanet server is limited to synchronisation of the measurement data
channels ("histdata0" - "histdata9") and configuration blocks ("config0" - "config9") between the
myDatalogEASY IoTmini and server. The Data Descriptor defined by the customer must divide the
measurement data channels and configuration blocks into the individual data fields.
l
Customer-specific server with web interface for the clients (optional)
It can be used to create an individual web interface for the clients. Two options are possible depending
on which source is used to obtain the data:
l
l
Customer-specific server that reads its data via the API interface (see "API" on page 187) from
the myDatanet server.
Customer-specific server that receives its data via LoRaWAN connection from the
myDatalogEASY IoTmini .
5.1 Recommended procedure
5.1.1 Development of M2M/IoT application
It is recommended to start with the definition of the Data Descriptor (see "Data Descriptor " on page 185)
when developing a M2M/IoT application. It specifies the various data structures (measurement data,
configurations, etc.) that are valid for the Device Logic as well as the myDatanet server. The definitions of the
Data Descriptor also apply for accessing the data of the myDatanet server via the API.
The information type should be taken into consideration when assigning the data to the relevant containers
("histdata0" - "histdata9" or "config0" - "config9"). The "histdata0" - "histdata9" containers should be used for
time series. If there is measurement data that will be generated frequently and data that will only be
generated rarely, it is recommended to use two different containers (e.g. "histdata0" for the frequently
generated and "histdata1" for the rarely generated). Similar also applies to the configuration data, for which
the "config0" - "config9" containers are provided. When it comes to the configuration data, it is recommended
to take a grouping based on logical context into consideration in addition to the frequency of change.
Note: A well thought out selection of the containers helps to reduce the required data volume and
associated costs.
5.2 Functionality of the internal data memory
Structure
Circular buffer
Total size
3MB
Number of sectors
8
Sector size
393.216 Byte
Rev. 01
29
The internal data memory of the myDatalogEASY IoTmini is designed as a circular buffer with 8 sectors. If the
entire memory (3MB ) is full, the sector with the oldest data is deleted fully before new data can be saved in
this sector again. This means that the internal data memory comprises at least 2,625 MB of valid data and a
maximum of 3MB .
For this reason, it is recommended to coordinate the data transmission and record interval in such a way that
a maximum of 2,625 MB has to be recorded between two transmissions. If it can be expected that individual
transmissions fail due to poor network coverage, this must also be taken into consideration when calculating
the data volume to be saved. Additionally, it must be noted that the system-related overhead is 10 Byte per
data record and that the first 8 Byte of each sector are reserved for the internal memory management. The 10
Byte overhead already includes the timestamp, so it does not have to be taken into account when calculating
the size of the entire record. If there is not enough free space in a sector to save the entire data record, the
data record is written to the next sector. This means that a data record is not written over the sector limits.
Note:
Additional explanation regarding the functionality of the circular buffer
Data memory after the first data is recorded:
Data memory once 3MB has been recorded
Data memory if further data is recorded once 3MB has already been recorded
Note:
Additional explanation on calculating the data volume to be saved:
To provide a clear and simple overview, the following example assumes that the sectors can only record two
complete data records.
1) Free memory in sector 1 is not enough to record a full data record (overhead + data).
30
Rev. 01
Chapter 5 Functional principle
5.3 Memory organisation
Organisation of the myDatalogEASY IoTmini memory
1)This memory block is only available if it was initialised via the "rM2M_RegInit()" function.
The size of the PAWN binary must not exceed 256kB for the transmission to the myDatalogEASY IoTmini . If
necessary, the data area of the PAWN binary can be compressed using a compiler instruction (#pragma
amxcompress <0-3>). The PAWN binary (256kB ), 10 configuration blocks (4000 Byte each), 4 registration
memory blocks (1kB each) and measurement data (3MB ) are stored in the flash memory of the
myDatalogEASY IoTmini . To execute via the PAWN script engine, the data area of the PAWN binary is
decompressed, if necessary, and copied to the RAM. The maximum size for the decompressed data area of
the PAWN binary in the RAM is 64kB . The optional registration memory blocks (e.g. REG_APP_STATE)
which can be initialized via the "RM2M_RegInit ()" function are also stored in RAM.
Rev. 01
31
5.4 Error handling
The following transmission mechanisms have been integrated in the firmware to ensure that problems with
the Device Logic can be diagnosed and resolved remotely. In the event that there is no Device Logic, a
connection to the myDatanet server is established every 24h . This backup interval is set to 1h if an existing
Device Logic has been deactivated due to an error being detected by the system. The "Interval & wakeup"
connection type is activated in both cases, which enables a connection to be initiated via the interface of the
myDatanet (see "myDatanet Server Manual " 805002).
5.5 Registration memory blocks
In addition to 4 1kB blocks, that are saved in the flash, another one, that is saved in the RAM, can optionally
be initialised via the "rM2M_RegInit()" function. Its size can be specified during initialisation, although it is
limited to a maximum of 1kB . The registration memory blocks provide the option of storing device-specific
data and synchronising it with the myDatanet server. The blocks only differs with regard to their access
options and storage location. This results in predefined intended uses that are described in the following
table:
Memory block
System-specific data
Access
Memory
Purpose
REG_SYS_OTP 1)
readable: Device Logic,
myDatanet server
FLASH
System information that is written once as
part of the production process
REG_SYS_FLASH 1)
readable: Device Logic,
myDatanet server
FLASH
System information that must be able to be
changed during operation
readable: Device Logic,
myDatanet server
FLASH
Application-specific information that is
written once as part of the production
process (recommendation, writing it multiple
times is not prevented by the firmware)
FLASH
Application-specific information that must be
able to be changed during operation
RAM
Application-specific information that must be
able to be changed during operation and
that does not require non-volatile storage in
the flash (e.g. current device status).
Application-specific data
REG_APP_OTP
writeable: Device Logic
REG_APP_FLASH
readable: Device Logic,
myDatanet server
writeable: Device Logic
Application-specific, volatile data
REG_APP_STATE 2)
readable: Device Logic,
myDatanet server
writeable: Device Logic
1) Writing data in these two memory blocks is reserved for the manufacturer.
2) This memory block is only available if it was initialised via the "rM2M_RegInit()" function.
Note: It is also possible to write in the memory blocks as part of the production process via the local
interfaces (USB and both UART). However, an agreement must be reached with the manufacturer to
receive information about this (see "Contact information" on page 209).
32
Rev. 01
Chapter 5 Functional principle
The "rM2M_RegGetString()", "rM2M_RegGetValue()", "rM2M_RegSetString()", "rM2M_RegSetValue()",
"rM2M_RegDelValue()" and "rM2M_RegDelKey()" functions are available for accessing the registration
memory blocks.
5.5.1 REG_SYS_FLASH
If the site that is linked to the device was created from an application template (see myDatanet Server Manual
805002), the registration memory block contains the following fields:
latestAppVersion
The latest available version of the application template installed on the device [16-bit unsigned]
installedAppVersion
Version of the application template currently installed on the device [16-bit unsigned]
appId
Application ID of the application installed on the device [max. 50 characters]
5.5.2 REG_APP_OTP
By saving the "Product Identity Profile" (PIP) in this registration memory block, the functions described in the
following can be initiated on the myDatanet server. The PIP consists of the following fields:
pipCustomer
Name of the customer to whom the site should be assigned [2-50 characters].
pipCtx
Name of the site that should be created/used [2-50 characters].
pipAppId
Application ID of the application template from which the site should be created [max. 50 characters].
pipAppVer (optional)
Version of the Device Logic currently installed on the device (e.g. "01v005") [6 characters].
pipCtxAutocreate (optional)
Indicates whether the site (if it does not exist yet) should be created ("0" or "1" must be saved as the
string)
"0": creation of a new site is not permissible
l "1": new site can be created (default)
l
If the myDatanet server receives a PIP, the two basic scenarios are differentiated:
l
There is no site with the name specified in the "pipCtx" field:
The new site is only created if the customer and application template were found on the myDatanet
server and "pipCtxAutocreate=1" or the field is missing.
l
A site with the name specified in the "pipCtx" field was found on the server:
In this case, the "pipCtxAutocreate" and "pipCustomer" fields are not relevant. The device is assigned
to the site, even if it is located within a different customer, if the application ID in the "pipAppId" field and
that of the found site match. The device is moved to the relevant customer for this purpose. The
allocation of the existing device is deallocated if a device is already assigned to the site. The existing
device is moved to the customer's pool.
Rev. 01
33
Chapter 6 Storage, delivery and transport
Chapter 6 Storage, delivery and transport
6.1 Inspection of incoming deliveries
Check the shipment immediately upon receipt to ensure it is complete and intact. Immediately report any
discovered transport damages to the delivering carrier. Also notify Microtronics Engineering GmbHin writing
about this without delay. Report any incompleteness of the delivery to the responsible representative or
directly to the company headquarters of the manufacturer within two weeks (see "Contact information" on
page 209).
Note: Any claims received thereafter will not be accepted.
6.2 Scope of supply
Note: The power supply unit required for operation (see "Power supply units" on page 204) and the
antenna (see "Antennas" on page 203) are not part of the standard scope of delivery and must be
ordered separately.
The standard scope of delivery of the myDatalogEASY IoTmini (301050) includes:
myDatalogEASY IoTmini base unit
2x cable screw connections (cable diameter of 5-10 mm)
l 2x blind plugs
l 2x 2-pin connector plug
l 2x 3-pin connector plug
l 1x 6-pin connector plug
l Housing cover
l 4x Delta PT M3.5x25 Torx 15
l myDatanet Tool Pen (206.646)
l MDN Magnet (206.803)
l Feature activation RS485 (300730)
l Feature activation LoRa (300971)
l Antenna LoRa FME -F(301004)
l PSU DC (300529)
l DIN rail mounting set for myDatanet housing 86x126 (206.634)
l
l
Additional accessories such as assembly sets, antennas, power supply units, charger, etc., depending on the
order. Please check these against the delivery slip.
Rev. 01
35
6.3 Storage
The following storage conditions must be observed:
myDatalogEASY IoTmini
Storage temperature
-30...+85°C
Humidity
15...90%rH
PSU713 BP
Operating temperature
-20...+50°C
(300526)
Storage temperature
+20...+25°C
PSU413D+ AP
Operating temperature
-20...+60°C
(300524)
Charging temperature
-20...+60°C
Storage temperature
0... +30°C
PSU413D AP
Operating temperature
-20...+60°C
(300525)
Charging temperature
0...+40°C
Storage temperature
0...+35°C
Note: The table above only contains the storage conditions for the energy sources used most frequently for the
myDatalogEASY IoTmini . Please consult the appropriate factsheet for information about the storage
conditions of other power supply units.
Note: If a Li-Ion rechargeable battery is to be stored for a longer period, it is recommended to ensure
that the charge level is 40% to 60% of the maximum charge.
Important note: Remove the power supply unit from the myDatalogEASY IoTmini prior to storage.
Store the measurement technology so that it is protected against corrosive or organic solvent vapours,
radioactive emissions as well as strong electromagnetic radiation.
6.4 Transport
Protect the myDatalogEASY IoTmini against heavy shocks, bumps, impacts or vibrations. The original
packaging must always be used for transport.
6.4.1 Transporting power supply units
WARNING:
With the exception of the PSU DC (300529), the power supply units required to operate the
myDatalogEASY IoTmini are classified as hazardous goods due to the installed
rechargeable batteries or battery packs for which the following conditions must be
observed during transport.
The guidelines that must be observed when transporting hazardous goods are dependent on the selected
transport route and are designed as follows:
Transport by road: ADR Directive
Transport by air: IATA guideline
l Transport by rail: RID guideline
l Transport by ship: IMDG guideline
l
l
36
Rev. 01
Chapter 6 Storage, delivery and transport
The following parties must observe these guidelines:
Shipping and packaging company
l Haulage contractors
l Air carriers and ground handling service providers (only if the IATA guideline is applied)
l Security personnel (particularly if the IATA guideline is applied)
l
When it comes to transporting hazardous goods, the most important tasks of the shipping and packaging
company are:
Classification / identification
Packaging
l Marking and labelling (e.g. transport stickers)
l Documentation (e.g. ADR transport documents or Dangerous Goods Declaration)
l
l
The energy stores of the power supply unit are lithium batteries. The following points must therefore be
observed in conjunction with transporting lithium batteries:
l
l
l
Type of lithium battery
l Lithium ion battery
l Lithium metal battery
Battery energy content
l If the energy content is within the "exempt" level, this will make the transportation process easier.
l If the energy content is above the "exempt" level, the battery is classed as a "complete"
hazardous material in accordance with the relevant guideline.
Scope of the delivered package
l Battery packed individually
l Battery packed with or in the equipment
Other matters that must be taken into consideration during transport preparation and processing:
Net weight per package
Involved air carrier (only if the IATA guideline is applied)
l Destination country (only if the IATA guideline is applied)
l
l
Important note: All of these points must be observed when compiling each delivery (including the
interdependencies).
Rev. 01
37
The "shipping and packaging company" can refer to the information provided in the following table to classify
the power supply units and subsequently determine which transport guideline to apply.
Title of the
Order
PSU
number
PSU413D+ AP 300524
Type of lithium battery Energy [Wh] Lithium content [g] UN number
Lithium ions
50,32Wh
UN3480
PSU413D AP
300525
Lithium ions
48,84Wh
UN3480
PSU713 BP
300526
Lithium metal
PSU AC
300558
Lithium ions
3,33Wh
UN3480
PSU DC+
300798
Lithium ions
3,33Wh
UN3480
6,6g
UN3090
6.5 Return
Every return must be accompanied by a fully field-out return form. This return form is available in the service
area of the myDatanet server. An RMA number is mandatory for any returns and can be obtained from the
Support & Service Centre (see "Contact information" on page 209). The return shipment of the
myDatalogEASY IoTmini must occur in the original packaging and with freight and insurance paid to
Microtronics Engineering GmbH (see "Contact information" on page 209). Insufficiently cleared return
shipments will otherwise not be accepted!
38
Rev. 01
Chapter 7 Installation
Chapter 7 Installation
Important note: To prevent any damage to the device, the work described in this section of the
instructions must only be performed by qualified personnel.
7.1 Dimensions
Dimensions: width and height
(view of a device after assembly)
Dimensions: depth
(view of a device after assembly)
7.2 Assembling the myDatalogEASY IoTmini
Important note:
All wiring work must be performed in the de-energised state.
Ensure installation is completed correctly.
l Improper handling can cause injuries and/or damage to the instruments.
l The myDatalogEASY IoTmini must not be operated in the field with the lid open.
l To ensure the housing is properly sealed, each of the cable screw connections must only hold a
single cable.
l
l
The myDatalogEASY IoTmini is split into several components when delivered and must therefore be
assembled before use.
Rev. 01
39
Components of the myDatalogEASY IoTmini
1 Connector plug (2x 2-pin, 2x 3-pin, 1x 6-pin)
4 myDatalogEASY IoTmini base unit
2 Power supply unit (not included in scope of
delivery)
5 4x Delta PT M3.5x25 Torx 15
3 2x cable screw connections (cable diameter of 510 mm)
6 Housing cover
40
Rev. 01
Chapter 7 Installation
1. Check that the content of the pack is complete.
2. Turn the locking nut of the cable screw connection clockwise (left-hand thread) to the stop to increase
the distance between the locking nut and engagement hook and thus make it easier to insert the cable
screw connection into the hole in the myDatalogEASY IoTmini base unit. The engagement hook is not
symmetrical. One of the lugs on the engagement hook is longer.
Fig. 1 - preparing the cable screw connection
Fig. 2 - preparing the cable screw connection
1 Engagement hook
3 Longer lug on the engagement hook
2 Locking nut
Rev. 01
41
3. First of all thread the connection cables of your sensors, actuators and, if necessary, the supply or
charging voltage through one of the cable screw connections in accordance with the following figure,
and then through one of the holes in the myDatalogEASY IoTmini base unit. Then connect the cables
to the connector plugs as described in chapter "Connecting the sensors, actuators and power supply"
on page 50. Depending on how flexible the cables are, it may be advantageous to connect them to the
connector plugs before the connector plugs are inserted in to the myDatalogEASY IoTmini base unit.
Important note: Only a single cable must be threaded through the cable screw connections to
ensure the seal of the housing is not jeopardised.
Threading the connection cables in
1 Cable screw connection (cable diameter of 510 mm)
3 Connector plug (2x 2-pin, 2x 3-pin, 1x 6-pin)
2 Connection cable of a sensor, actuator or the
supply or charging voltage
4. In accordance with the following figures, thread the engagement hook with the side that has the longer
lug first (see "Fig. 2 - preparing the cable screw connection" on page 41) through the hole in the
myDatalogEASY IoTmini base unit. The cables that have already been threaded in are not illustrated in
this figure in the interests of clarity.
Fig. 1 - threading in the cable screw
connection
42
Fig. 2 - threading in the cable screw
connection
Fig. 3 - threading in the cable screw
connection
Rev. 01
Chapter 7 Installation
5. Tighten the locking nut by turning it clockwise (left-hand thread).
Important note: Ensure that the seal is clean and intact before tightening. Remove any
impurities and/or dirt. The manufacturer shall not be liable for any damage to the device caused
by leaky or faulty seals.
6. Check that the seal for the cable screw connection is positioned correctly on all sides and that no
foreign materials have been trapped between the housing, seal and locking nut.
Important note: The manufacturer is not liable for any damage that is caused by seals that
are not positioned correctly.
7. Connect the antenna (see "Connecting the LoRa antenna" on page 54). The antenna is not included in
the scope of delivery and must be ordered separately.
8. Insert the power supply unit. The power supply unit is designed in such a way that it cannot be inserted
incorrectly.
Note: Note that all power supply units with an integrated and rechargeable energy store are delivered
with a maximum charge of 30% in accordance with applicable transport regulations and must therefore
be fully charged before being used for the first time (see "Charging the power supply unit" on page 191).
Inserting the power supply unit
1 Power supply unit
2 myDatalogEASY IoTmini base unit
The following step is not mandatory.
9. Check whether the connection to the myDatanet server has worked correctly (see "Testing
communication with the device" on page 69).
Rev. 01
43
10. Close the housing cover. The best option is to tighten the four screws crosswise (torque 0,5Nm; At the
first screw 0,7Nm because the threads have to be shaped into the base part first.) so that the housing
cover is positioned evenly.
Important note: Ensure that the seals are clean and intact before closing the housing cover.
Remove any impurities and/or dirt. The manufacturer shall not be liable for any damage to the
device caused by leaky or faulty seals.
Closing the housing cover
1 myDatalogEASY IoTmini base unit
3 Housing cover
2 Delta PT M3.5x25 Torx 15
11. Check that the housing cover is positioned correctly on all sides and that no foreign materials have
been trapped between the housing and housing cover.
Important note: The manufacturer is not liable for any damage that is caused by housing
covers that are not closed correctly.
The following step is only necessary if you are using an external supply or charging voltage.
12. Now switch on the external supply or charging voltage.
Note: If you are using a power supply unit without an integrated energy store, the external supply or
charging voltage must be switched on before the optional step during which the connection to the server
is tested.
44
Rev. 01
Chapter 7 Installation
7.3 Installing the myDatalogEASY IoTmini
Important note:
Ensure installation is completed correctly.
Comply with existing legal and/or operational directives.
l Improper handling can cause injuries and/or damage to the devices.
l The myDatalogEASY IoTmini must not be operated in the field with the lid open.
l The pressure compensation must be protected against contamination.
l The myDatalogEASY IoTmini is not approved for use in closed channels.
l
l
The installation site must be selected according to specific criteria. The following conditions must be avoided
in any case:
Direct sunlight
Direct weather exposure (rain, snow, etc.)
l Objects that radiate intense heat (maximum ambient temperature: -20...+60°C )
l Objects with a strong electromagnetic field (frequency converter or similar)
l Corrosive chemicals or gases
l Mechanical impacts
l Direct installation on paths or roads
l Vibrations
l Radioactive emissions
l
l
Note: Leave sufficient space at the upper end to install the antenna. The space required depends on the
antenna used. Approx. 15 cm of space must be left beneath the device for the cable connections. Further
information regarding the installation dimensions can be found in the relevant sub-chapter.
Rev. 01
45
7.3.1 Wall mounting
For wall mounting the optional "Universal bracket for housing myDatanet 86x126 (206.640)" equipment is
required.
Step 1 of the wall mounting
1 myDatalogEASY IoTmini
Step 2 of the wall mounting
3 Assembly loop (included in the delivery scope of
206.640)
2 Delta PT M3.5x8 Torx 15 (included in the delivery 4 Raised head tapping screw 3.5x32 (included in
scope of 206.640)
the delivery scope of 206.640)
1. First attach the assembly loop (3) using the screws (2) included in the "Universal bracket for housing
myDatanet 86x126 (206.640)" equipment set to the myDatalogEASY IoTmini (see "Step 1 of the wall
mounting" on page 46).
2. Drilling the holes for mounting:
If you want to use the tapping screws (4) included in the equipment set to secure the assembly loop
(3) to the wall, drill four 6-mm holes in the wall using the drill template as a guide in accordance with
the dimensions in the diagram "Step 2 of the wall mounting" on page 46.
If you want to use your own fastening screws you can use the drill guide provided in the equipment
set to determine the position of the holes. The diameters are then determined by the screws that are
being used and any wall plugs that may be required.
3. Securing the myDatalogEASY IoTmini to the wall:
If you want to use the tapping screws (4) included in the equipment set, first of all insert the supplied
wall plugs into each of the four drill holes before screwing the myDatalogEASY IoTmini with the
attached assembly loop (3) to the wall (see "Step 2 of the wall mounting" on page 46).
If you are using your own screws, you must also insert the wall plugs into the holes before mounting
the myDatalogEASY IoTmini with the attached assembly loop (3) to the wall (see "Step 2 of the wall
mounting" on page 46).
46
Rev. 01
Chapter 7 Installation
7.3.2 Top-hat rail assembly
The "DIN rail mounting set for myDatanet housing 86x126 (206.634)" equipment is required for the top-hat
rail assembly.
Step 1 of the top-hat rail assembly
Step 2 of the top-hat rail assembly
1 myDatalogEASY IoTmini
3 Assembly loop (included in the scope of delivery of
206.634)
2 Delta PT M3.5x8 Torx 15 (included in the scope of
delivery of 206.634)
1. First attach the assembly loop (3) using the screws (2) included in the "DIN rail mounting set for
myDatanet housing 86x126 (206.634)" equipment set to the myDatalogEASY IoTmini (see "Step 1 of
the top-hat rail assembly " on page 47).
2. Place the assembly loop (3) onto the top edge of the top-hat rail. When turned slightly around the
horizontal axis of the myDatalogEASY IoTmini with the assembly loop (3) attached, the assembly loop
(3) engages on the top-hat rail (see "Step 2 of the top-hat rail assembly" on page 47).
Rev. 01
47
7.3.3 Pipe assembly
The optional "Pipe mounting kit for myDatanet housing 86x126 (206.660)" equipment is required for the pipe
assembly.
Step 1 of the pipe assembly
Step 2 of the pipe assembly
1 myDatalogEASY IoTmini
3 Assembly loop (included in the scope of delivery of
206.660)
2 Delta PT M3.5x8 Torx 15 (included in the scope of 4 Cable binder (included in the scope of delivery of
delivery of 206.660)
206.660)
1. First attach the assembly loop (3) using the screws (2) included in the "Pipe mounting kit for myDatanet
housing 86x126 (206.660)" equipment set to the myDatalogEASY IoTmini (see "Step 1 of the pipe
assembly " on page 48).
2. Position the myDatalogEASY IoTmini with the attached assembly loop (3) on the pipe and use the
supplied cable binders (4) to secure the myDatalogEASY IoTmini (see "Step 2 of the pipe assembly"
on page 48).
48
Rev. 01
Chapter 7 Installation
7.4 Safety instructions for the cabling
Important note: To avoid any damage, always switch off the voltage supply to the device when
performing electrical connections.
When connections are made to the myDatalogEASY IoTmini , the following warnings and information must
be observed, in addition to the warnings and information found in the individual chapters on the installation.
Further safety information is included in "Safety instructions" on page 17.
Remove the power supply unit from the device before completing any wiring work.
Removing the power supply unit
1 Delta PT M3.5x25 Torx 15
3 Housing cover
2 Power supply unit
4 Strap to remove the power supply unit
Rev. 01
49
7.4.1 Information on preventing electrostatic discharges (ESD)
Important note: Maintenance procedures that do not require the device to be connected to the
power supply should only be performed once the device has been disconnected from the mains
power supply to minimise hazards and ESD risks.
The sensitive electronic components inside the device can be damaged by static electricity, which can impair
the device performance or even cause the device to fail. The manufacturer recommends the following steps
to prevent any damage to the device caused by electrostatic discharges:
Discharge any static electricity present on your body before handling the electronic components of the
device (such as circuit boards and components attached thereto). To do this, you can touch a grounded
metallic surface such as the housing frame of a device or a metal pipe.
l Avoid any unnecessary movements to prevent the build-up of static charges.
l Use antistatic containers or packaging to transport components that are sensitive to static.
l Wear an antistatic wristband that is grounded via a cable to discharge your body and keep it free of
static electricity.
l Only touch components that are sensitive to electric charges in an antistatic working area. If possible,
use antistatic mats and work pads.
l
7.5 Electrical installation
Important note: Only qualified personnel should undertake the installation described in this chapter
of the operating instructions to avoid any damage to the device.
7.5.1 Connecting the sensors, actuators and power supply
Important note:
All wiring work must be performed in the de-energised state.
Ensure installation is completed correctly.
l Comply with existing legal and/or operational directives.
l Improper handling can cause injuries and/or damage to the instruments!
l Run all data and power cables so that they do not pose a trip hazard and ensure that cables do
not have any sharp bends.
l The myDatalogEASY IoTmini must not be operated in the field with the lid open.
l The myDatalogEASY IoTmini cannot be operated without a power supply unit.
l To ensure the housing is properly sealed, each of the 2 cable screw connections must only hold
a single cable.
l
l
50
Rev. 01
Chapter 7 Installation
Connection of the sensors and power supply (view without power supply unit)
1 Mini-B USB (only for debug and script update)
3 Main terminal block (split into 2x 2-pin, 2x 3-pin, 1x
6-pin)
2 RS232 interface (7-pin JST connector)
4 Cable screw connection (cable diameter of 510 mm)
Assignment of the RS232 interface
1 SHIELD
Cable shielding
2
GND
Ground
3
RTS
RTS line of the RS232 interface
4
CTS
CTS line of the RS232 interface
5
RXD
RXD line of the RS232 interface
6
TXD
TXD line of the RS232 interface
7
VEXTRS232 Switchable sensor supply (3,3V )
Rev. 01
51
Assignment of the main terminal block
V IN
External supply or charging voltage
GND
Ground (external supply or charging voltage)
NO
Isolated switch contact
CC
VEXT
Switchable sensor supply (3,3V )
GND
Ground
UI 1
Universal input 1
UI 2
Universal input 2
UI3/A+
Universal input 3 / RS485 A 1)
UI 4/B-
Universal input 4 / RS485 B 1)
GND
Ground
VOUT
Switchable and adjustable sensor supply (5...24V >)
GND
Ground
RTD+
RTD-
Clamps for the external temperature sensor (two or three
wires)
TCOM
1) The RS485 interface is only available if the universal inputs 3 and 4 are not being used.
Note: The first two steps are only necessary if the device is already in operation and the wiring needs
to be modified.
1. Remove the four screws that secure the housing cover. Now open the myDatalogEASY IoTmini .
Important note: In the event of adverse weather conditions including rain or in a location
where water can penetrate from above, suitable measures must be implemented to protect the
device from penetrating moisture when the housing cover is open.
2. Remove the power supply unit from the myDatalogEASY IoTmini . Use the strap provided to remove
the power supply unit.
3. Then connect your sensors and actuators with the universal inputs and outputs. You will require a
cable with a 7-pin JST connector to connect the sensors and actuators to the RS232 interfaces.
Ensure that no current is present when establishing the connection. If you would like to use an external
supply or charging voltage, you should connect the corresponding cables with the V IN and GND
clamps in the de-energised state.
Important note: Only a single cable must be threaded through the cable screw connections to
ensure the seal of the housing is not jeopardised.
4. Tighten the cable screw connections to secure the cables.
5. Affix blind plugs to all of the cable screw connections that are not required.
Important note: All unused cable screw connections on the myDatalogEASY IoTmini must
be sealed watertightly using the blind plugs supplied. Otherwise the degree of protection for the
entire device is not guaranteed and the manufacturer's warranty is void.
52
Rev. 01
Chapter 7 Installation
6. Connect the antenna (see "Connecting the LoRa antenna" on page 54). The antenna is not included in
the scope of delivery and must be ordered separately.
7. Insert the power supply unit.
The following step is not mandatory.
8. Check whether the connection to the myDatanet has worked correctly (see "Testing communication
with the device" on page 69).
9. Close the housing cover. The best option is to tighten the four screws crosswise (torque 0,5Nm; At the
first screw 0,7Nm because the threads have to be shaped into the base part first.) so that the housing
cover is positioned evenly.
Important note: Ensure that the seals are clean and intact before closing the housing cover.
Remove any impurities and/or dirt. The manufacturer shall not be liable for any damage to the
device caused by leaky or faulty seals.
Closing the housing cover
1 myDatalogEASY IoTmini base unit
3 Housing cover
2 Delta PT M3.5x25 Torx 15
10. Check that the housing cover is positioned correctly on all sides and that no foreign materials have
been trapped between the housing and housing cover.
Important note: The manufacturer is not liable for any damage that is caused by housing
covers that are not closed correctly.
Rev. 01
53
The following step is only necessary if you are using an external supply or charging voltage.
11. Now switch on the external supply or charging voltage.
Note: If you are using a power supply unit without an integrated energy store, the external supply or
charging voltage must be switched on before the optional step during which the connection to the server
is tested.
7.5.1.1 Connection examples
Connection examples
1 Main terminal block of the
myDatalogEASY IoTmini
4 2-wire mA sensor
2 Isolated relay contact
5 3-wire mA sensor or 3-wire U-sensor
3 Sensor with open collector output
Note: The "Counter", "Frequency" and "PWM" operating modes require a permanent supply of the
sensors. One of the two switchable sensor supplies must be permanently active for this purpose. The
use of VEXT is recommended for this purpose (see sensor 1 in the connection example above). The
power consumption per input when the switch contact is closed can be up to 384µA due to the load of
10k086 .
7.5.2 Connecting the LoRa antenna
Important note: To ensure the correct functionality, only use antennas that are supplied by the
manufacturer.
The standard antenna (Antenna LoRa FME -F, 301004) is attached directly to the antenna connector (see
"Overview" on page 20) of the myDatalogEASY IoTmini .
If the distance between the antenna position and the myDatalogEASY IoTmini is too great, you can use a 5m
Extension cable for antenna FME-F/FME-M 5m (206.805).
1. Ensure that the myDatalogEASY IoTmini is de-energised.
2. If you need an antenna extension, connect it to the antenna first.
54
Rev. 01
Chapter 7 Installation
3. Connect the antenna extension or antenna directly to the antenna connector of the
myDatalogEASY IoTmini (see "Overview" on page 20)
Important note: Do not apply too much force when tightening the antenna. Do not use any
tools to tighten the antenna or antenna extension; only tighten it manually.
4. Switch the voltage supply of the myDatalogEASY IoTmini back on.
The following step is not mandatory.
5. Check whether the connection to the myDatanet server has worked correctly (see "Testing
communication with the device" on page 69).
7.5.3 Technical details about the universal inputs
Note: The universal inputs 3 and 4 are only available if the RS485 interface is not used.
Note: The universal inputs are not electrically isolated.
7.5.3.1 0/4 to 20mA mode
Note: Above 23,96mA, the relevant input becomes highly resistive (safety shutdown to prevent damage to the
universal input).
Resolution
6,3µA
Imax
23,96mA
Load
96Ω
7.5.3.2 0 to 2V mode
Resolution
610µV
Umax
2,5V
Load
10k086
7.5.3.3 0 to 10V mode
Resolution
7,97mV
Umax
32V
Load
4k7
Rev. 01
55
7.5.3.4 Standard digital modes (PWM, frequency, digital, counter)
General
Umax
32V
Low
<0,99V
High
>2,31V
Load
10k086
Measurement
range
1...99%
fmax
100Hz
Minimum pulse
length
1ms
Frequency
Measurement
range
1...1000Hz
Counter
Minimum pulse
length
1ms
PWM
7.5.4 Technical details about the PT100/1000 interface
The interface for the external temperature sensor automatically detects whether a PT100 or PT1000 is being
used. It is also possible to use three- or two-wire sensors. An additional link is required on two-wire sensors
(see "PT100/PT1000 2-wire" on page 56).
PT100/PT1000 3-wire
PT100/PT1000 2-wire
7.5.5 Technical details about the RS485 interface
Note: The RS485 interface corresponds to standard EIA-485.
The RS485 interface of the myDatalogEASY IoTmini includes an input common mode range that covers the
full area specified for RS485 (-7V...+12V). Higher voltages damage the interface. Differential signals of more
than +/-200mV within the specified input common mode range are detected correctly. In send mode, the
output signal is in the range of 1,5...3,3V .
Baud rate
600-115200
Stop bits
1, 2
Parity
N, E, O
Data bits
7, 8
Load
resistance
Off
56
120Ω
Rev. 01
Chapter 7 Installation
The 120Ω load resistance between RS485 A and B can be activated via the "RS485_Init()" function.
Schematic diagram of the switchable load resistance
Note: Additional explanation regarding the connection of two RS485 bus participants
Schematic diagram: Connection of two RS485 bus participants
A problem occurs if there is no connection between the GND potentials of the sender and recipient. A common
mode voltage (VCM) occurs in this case. The GND potential difference must not exceed max. +/- 7V . Higher
voltages will damage the interface. Temporary overvoltages (ESD, EFT and surge) are, however, absorbed by
protective circuits.
Note: The common mode input voltage range of -7V...+12V specified for the RS485 is determined from the
max. permissible GND potential difference (+/- 7V ) and the max. permissible output voltage range of 0...5 V for
RS485.
7.5.6 Technical details about the RS232 interface
Note: The RS232 interface of the myDatalogEASY IoTmini is compatible with standard TIA/EIA232-F.
The output drivers are protected against overloading and are not damaged by a short circuit to the GND or +/15 V. The inputs are equipped with a 5 kΩ load resistance.
Baud rate
600-115200
Stop bits
1, 2
Parity
N, E, O
Data bits
7, 8
Flow control Off
RTS/CTS
The direction of the signals corresponds to that of a DTE (e.g. PC).
Rev. 01
57
Switching thresholds
Signal Type
Low
TXD
O
-5,4V
5,4V
RXD
I
<0,8V
>2V
CTS
I
<0,8V
>2V
RTS
O
-5,4V
5,4V
High
7.5.7 Technical details about the USB interface
The connection to a PC is established via the USB slave interface. It is only designated for the communication
with the web-based development environment rapidM2M Studio or the DeviceConfig configuration program.
It is not possible to access the USB interface via the device logic. A detailed description of the rapidM2M
Studio web-based development environment is provided in chapter "rapidM2M Studio " on page 79.
Explanations regarding the functionality of the DeviceConfig configuration program is provided in the manual
for the DeviceConfig ("myDatanetDeviceConfig Manual " 805004).
Access to the web-based development environment rapidM2M Studio is included in the Microtronics Partner
Program, for which you can register free of charge at the following address:
https://partner.microtronics.com
The DeviceConfig configuration program can be downloaded free of charge from the following website:
www.microtronics.com/deviceconfig
Important note: If the antenna of the device is earthed or connected to the ground potential of
another object (e.g. installation on a control cabinet), remove the antennas before you connect the
device with the USB interface of a PC. Otherwise, this can cause a potential displacement between
the ground of the antenna and the ground of the PC, which could damage the USB interface of the
device.
58
Rev. 01
Chapter 7 Installation
7.5.8 Technical details about the outputs
7.5.8.1 Switchable sensor supply VOUT
Note: The switchable sensor supply output is short-circuit-proof.
The output voltage can be varied in the range of 5...24V using the Device Logic (see "Vsens_On()").
Output voltage characteristics subject to the load current for VOUT = 5V
Output voltage characteristics subject to the load current for VOUT = 12V
Rev. 01
59
Output voltage characteristics subject to the load current for VOUT = 15V
Output voltage characteristics subject to the load current for VOUT = 24V
7.5.8.2 Switchable sensor supply VEXT
Note: The switchable sensor supply output is short-circuit-proof.
The switchable sensor supply VEXT is applied to the main terminal block (see "Connecting the sensors,
actuators and power supply" on page 50).
Uout
3,3V
Imax
180mA
60
Rev. 01
Chapter 7 Installation
7.5.8.3 Switchable sensor supply VEXTRS232
Note: The switchable sensor supply output is short-circuit-proof.
The switchable sensor supply VEXTRS232 is applied to the connector of the RS232 interface (see
"Connecting the sensors, actuators and power supply" on page 50).
Uout
3,3V
Imax
180mA
7.5.8.4 Isolated switch contact (NO, CC)
Important note: The user must ensure that the current on the isolated switch contact does not
exceed 130mA .
Equivalent circuit diagram for the isolated switch contact
Imax
130mA
Umax
32V
Ron
35Ω
fmax
1000Hz
7.5.9 Technical details about energy management
The Device Logic execution is only stopped if the internal supply voltage falls below 2,9V and the
myDatalogEASY IoTmini switches to energy saving mode in which only the charge control is active. In this
case, the charge control tries to charge the rechargeable battery up to 3,8V . The "UV_LOCKOUT" log entry
is also entered in the device log when activating energy saving mode. The rechargeable battery of the power
supply unit can be charged up again if the device is in energy saving mode and an external supply or charging
voltage (V IN) is connected. Otherwise the myDatalogEASY IoTmini remains in this energy saving mode until
the rechargeable battery is completely discharged.
Energy saving mode is terminated and Device Logic execution is activated again, once the rechargeable
battery voltage exceeds 3,2V when recharging.
Rev. 01
61
When an external supply or charging voltage (V IN) is used, the charge control ensures that the rechargeable
battery of the power supply unit is charged. The following operating states are possible:
l
Active energy saving mode (i.e. Device Logic inactive) or no Device Logic installed:
The charge control tries to charge the rechargeable battery to 3,8V or to maintain the voltage at this
level.
l
Device Logic active but the charge control was not configured via the "PM_SetChargingMode"
function:
The charge control is activated and the rechargeable battery is charged to the maximum voltage if the
state of charge of the rechargeable battery for the power supply unit falls below 50%. The charge
control is then deactivated again. This is designed to optimise the service life of the rechargeable
battery.
l
Device Logic active and the charge control was configured via the Device Logic:
The functionality of the charge control can be configured via the "PM_SetChargingMode" function.
There are three options available:
l
l
l
PM_CHARGING_OFF: Charge control deactivated
PM_CHARGING_NORMAL: The charge control is activated and the rechargeable battery is
charged to the maximum voltage if the state of charge of the rechargeable battery for the power
supply unit falls below 50%. The charge control is then deactivated again. This is designed to
optimise the service life of the rechargeable battery.
PM_CHARGING_SOLAR: The rechargeable battery of the power supply unit is charged to the
maximum voltage if the supply or charging voltage V IN exceeds 16V . The charge control then
remains deactivated for 12 hours unless the state of charge of the rechargeable battery for the
power supply unit drops below 95%. This charge strategy is recommended if a solar field is used
to charge the rechargeable battery.
The charge control reads out any additional information that is required, such as the maximum voltage and
ambient temperature at which charging is permitted, directly from the memory of the power supply unit. In
both charge strategies, recharging is only completed if the ambient temperature does not exceed the
permissible range of the charging temperature. The permissible charging temperature is specified in the
factsheet for the relevant power supply unit. Chapter "Power supply units" on page 204 contains an overview
of the temperature ranges of the power supply units.
7.5.10 Technical details about the energy supply
Schematic diagram of the energy supply
62
Rev. 01
Chapter 7 Installation
V IN
12...32VDC
Power consumption
typ. <1mW 1)
(without sensors)
max. 12W
Reverse voltage
protection
Yes
1) applies to continuous operation if the possibly available rechargeable battery of the power supply unit is fully charged
A selection of compatible power supplies is included in the chapter "Charging devices and power supply
units" on page 204. The supply voltage input is equipped with a diode to protect against polarity reversal.
Depending on the type, the power supply unit contains a rechargeable battery (PSU413D+ AP , PSU413D
AP ), a battery (PSU713 BP ), a power supply unit and a rechargeable battery (PSU AC ) or only a protective
circuit (PSU DC ). A list of compatible PSUs is included in the chapter "Power supply units" on page 204. An
external supply or charging voltage is not required if the power supply unit is equipped with a battery.
7.5.10.1 PSU413D+ AP (300524)
V IN
Optional
Protective circuit (V IN)
Overvoltage protection
Capacity
13,6Ah
50,32Wh
Type
Li-Ion
Rechargeable
Yes
Nominal voltage of the
rechargeable battery
3,75V
Operating temperature
-20...+60°C
Charging temperature
-20...+60°C
Storage temperature
0... +30°C
Block diagram of the PSU413D+ AP
7.5.10.2 PSU413D AP (300525)
V IN
Optional
Protective circuit (V IN)
Overvoltage protection
Capacity
13,2Ah
48,84Wh
Type
Li-Ion
Rechargeable
Yes
Nominal voltage of the
rechargeable battery
3,7V
Operating temperature
-20...+60°C
Charging temperature
0...+40°C
Storage temperature
0...+35°C
Rev. 01
Block diagram of the PSU413D AP
63
7.5.10.3 PSU713 BP (300526)
V IN
Not required
Protective circuit (V IN)
---
Capacity
13Ah
93,6Wh
Type
Li-SOCl2
Rechargeable
No
Nominal voltage
7,2V
Operating temperature
-20...+50°C
Charging temperature
---
Storage temperature
+20...+25°C
Block diagram of the PSU713 BP
7.5.10.4 PSU DC (300529)
V IN
Required
Protective circuit (V IN)
DC-Protection circuit
Capacity
---
Type
---
Rechargeable
no
Nominal voltage
---
Operating temperature
-20...+60°C
Charging temperature
---
Storage temperature
0... +35°C
Block diagram of the PSU DC
7.5.10.5 PSU AC (300558)
V IN
Not required
Protective circuit (V IN)
---
AC supply voltage
230VAC
Capacity
900mAh
3,33Wh
Type
Li-Po
Rechargeable
Yes
Nominal voltage
3,7V
Operating temperature
-20...+60°C
Charging temperature
0...+40°C
Storage temperature
0... +35°C
64
Block diagram of the PSU AC
Rev. 01
Chapter 7 Installation
7.5.10.6 PSU DC+ (300798)
V IN
Required
Protective circuit (V IN)
DC-Protection circuit
Capacity
900mAh
3,33Wh
Type
Li-Po
Rechargeable
yes
Nominal voltage
3,7V
Operating temperature
-20...+60°C
Charging temperature
0...+40°C
Storage temperature
0... +35°C
Block diagram of the PSU DC+
7.5.11 Technical details about the system time
The myDatalogEASY IoTmini is equipped with a hardware real-time clock that has its own buffer battery with
an expected service life of >10 years. The system time continues to run even if the power supply unit is
removed. This means that following recommissioning, valid time stamps for the measurement and log data
can be generated immediately. Additionally, the system time is synchronised with the server each time a
connection to the myDatanet server is established.
Rev. 01
65
Chapter 8 Initial Start-Up
Chapter 8 Initial Start-Up
8.1 User information
Before you connect the myDatalogEASY IoTmini and place it into operation, you must observe and comply
with the following user information!
This manual contains all information that is required for using the device.
Is intended for technically qualified personnel who have the relevant knowledge and experience in the area of
measurement technology.
Read this manual carefully and completely in order to ensure the proper functioning of the
myDatalogEASY IoTmini .
Contact Microtronics Engineering GmbH(see "Contact information" on page 209) if anything is unclear or if
you encounter difficulties with regard to installation, connection or configuration.
8.2 Applicable documents
In addition to this operating instructions, additional instructions or technical descriptions may be required for
the installation, commissioning and operation of the entire system.
These instructions are enclosed to the respective additional devices or sensors or are available for download
on the Microtronics website.
8.3 General principles
The entire measurement system may only be placed into operation after completion and inspection of the
installation. Study the manual thoroughly before placing into operation to prevent faulty or incorrect
configuration.
Utilise the manual to familiarise yourself with the operation of the myDatalogEASY IoTmini and the input
screens of the myDatanet server before you begin with the configuration.
8.4 Commissioning the system
Note: It is recommended that the myDatalogEASY IoTmini is first placed into operation in the office before
mounting the device permanently at the place of use. During this process, you should create a site for the later
operation on the myDatanet server (see "Creating the site" on page 81) and determine a site configuration
(including Data Descriptor and Device Logic) (see "Site configuration" on page 72). If you create the site based
on an IoT application (see "myDatanet Server Manual " 805002), the Data Descriptor and Device Logic are
taken from the IoT application and do not need to be defined separately. Take the opportunity to get to know the
functions of the device in a stable environment. You can also use suitable test signals to simulate the sensors
to establish the optimum configuration of the myDatalogEASY IoTmini prior to its actual first use. This reduces
the amount of time required for on-site installation to a minimum.
Rev. 01
67
The following work should be completed in the office before you go to the future location of the device:
1. If necessary, create a customer on the myDatanet server (see "myDatanet Server Manual " 805002).
2. Within the selected customer, create a site/application for operation on the myDatanet server (see
"Creating the site" on page 81).
Note: A "rapidM2M " type site or a site based on an IoT application that is compatible with the
"rapidM2M " site type must be created to operate the myDatalogEASY IoTmini .
3. Configure the created site/application according to your requirements (see "Site configuration" on page
72). If the site was not created based on an IoT application, you must determine the Data Descriptor
and Device Logic via the "Control" configuration section (see "Control" on page 73).
4. Connect the antenna (see "Connecting the LoRa antenna" on page 54). The antenna is not included in
the scope of delivery and must be ordered separately.
5. Establish a connection so that the configuration of site is transferred to the myDatalogEASY IoTmini . If
no script has been loaded in the device yet, this can be achieved by inserting the power supply unit as
described in the chapter "Assembling the myDatalogEASY IoTmini " on page 39. If a Device Logic has
already been loaded in the device, execute the operations provided in the Device Logic to trigger the
establishment of a connection.
Note: Note that all power supply units with an integrated and rechargeable energy store are delivered
with a maximum charge of 30% in accordance with applicable transport regulations and must therefore
be fully charged before being used for the first time (see "Charging the power supply unit" on page 191).
Note: If you are using a power supply unit without an integrated energy store, the external supply or
charging voltage must be connected before inserting the power supply unit. Details on this are provided
in the chapter "Connecting the sensors, actuators and power supply" on page 50.
Note: You can also skip this step, as a connection must also be initiated during the installation on site,
which transfers the configuration to the myDatalogEASY IoTmini at the same time.
Inserting the power supply unit
1 Power supply unit
2 Base unit
6. Use the corresponding strap to remove the power supply unit from the myDatalogEASY IoTmini and
then, if used, disconnect the cabling for the supply or charging voltage from the device when in a deenergised state, if possible.
7. Remove the antenna again.
68
Rev. 01
Chapter 8 Initial Start-Up
The following work is completed directly at the location of the device:
8. Complete all of the steps detailed in the chapter "Assembling the myDatalogEASY IoTmini " on page
39.
9. Check whether the connection to the myDatanet server has worked correctly (see "Testing
communication with the device" on page 69).
8.5 Testing communication with the device
1. Create a site for operation on the myDatanet server (see "Creating the site" on page 81).
Note: A "rapidM2M " type site or a site based on an IoT application that is compatible with the
"rapidM2M " site type must be created to operate the myDatalogEASY IoTmini .
2. Configure the created site/application according to your requirements (see "Site configuration" on page
72). If the site was not created based on an IoT application, you must determine the Data Descriptor
and Device Logic via the "Control" configuration section (see "Control" on page 73).
3. Connect the antenna (see "Connecting the LoRa antenna" on page 54). The antenna is not included in
the scope of delivery and must be ordered separately.
4. Establish a connection. If no script has been loaded in the device yet, this can be achieved by inserting
the power supply unit as described in the chapter "Assembling the myDatalogEASY IoTmini " on page
39. If a Device Logic has already been loaded in the device, execute the operations provided in the
Device Logic to trigger the establishment of a connection.
Note: Note that all power supply units with an integrated and rechargeable energy store are delivered
with a maximum charge of 30% in accordance with applicable transport regulations and must therefore
be fully charged before being used for the first time (see "Charging the power supply unit" on page 191).
Note: If you are using a power supply unit without an integrated energy store, the external supply or
charging voltage must be connected before inserting the power supply unit. Details on this are provided
in the chapter "Connecting the sensors, actuators and power supply" on page 50.
Inserting the power supply unit
1 Power supply unit
Rev. 01
2 Base unit
69
5. Wait until the measurement instrument list indicates that the device is connected to the server (rotating
arrows).
With the exception of the "Online" connection type (see "rM2M_TxSetMode()"), the time during which
the myDatalogEASY IoTmini is connected to the server is very short. It can therefore also be checked
whether the time stamp of the last connection (under the green status symbol) has been updated.
The following steps are only necessary, if you simultaneously want to test the measurement value acquisition
and data transmission.
6. Complete all of the steps detailed in the chapter "Assembling the myDatalogEASY IoTmini " on page
39. This includes connecting the sensors.
Important note: All wiring work must be performed in the de-energised state.
7. You can use the "Reports" of the myDatanet server to check the data transmission (see "myDatanet
Server Manual " 805002). The configuration of the Data Descriptor (see "Data Descriptor " on page
185) is required for this purpose.
8. Once you have completed the necessary preparations, initiate a transmission directly on the device if
you have included this in your Device Logic. If you have not included an option to trigger a transmission,
wait for the next scheduled data transmission.
9. Evaluate the incoming data.
70
Rev. 01
Chapter 9 User interfaces
Chapter 9 User interfaces
The configuration of the myDatalogEASY IoTmini is carried out via the web interface on the myDatanet
server (see "User interface on the myDatanet server" on page 72), which your responsible sales partner will
provide to you.
9.1 User interface on the myDatalogEASY IoTmini
9.1.1 Operating elements
The operating elements of the myDatalogEASY IoTmini can still be operated when the housing is closed.
Operating elements
1 Solenoid switch
2 Two-colour LED
9.1.1.1 Solenoid switch
The solenoid switch is operated using the MDN Magnet (206.803) included in the scope of supply. The
"Switch_Init()" function can be used to determine whether the solenoid switch is evaluated by the firmware or
Device Logic.
Report
Firmware
Operation by the user
Press and hold for at least 3 sec.
and then release
Operation
Initiation of the transmission
Device Logic
Press
Call up of the public function, for which the index is
transferred to the "Switch_Init()"function
Release
9.1.1.2 Two-colour LED
The "Led_Init()" function can be used to determine whether the two-colour LED is controlled by the firmware
or Device Logic. If the two-colour LED has been configured in such a way that it is controlled by the firmware,
it is designed to signal the current operating state. The state of the two-colour LED can otherwise be
Rev. 01
71
controlled by the "Led_On()", "Led_Off()", "Led_Blink()" , "Led_Flash()" and "Led_Flicker()" Device Logic
functions.
Operating states (two-colour LED controlled by the firmware)
Two-colour LED Colour
Description
Flickering
Green Establishing connection
Lights up
Green GPRS connection or USB connection established
Off
---
Normal operation/script processing until the next transmission
9.2 User interface on the myDatanet server
9.2.1 Site configuration
Note: Depending on the respective user level, some of the configuration fields mentioned in the following subchapters may be hidden. In this case, please contact the administrator of the myDatanet server.
Click on the name of the site in the list of sites to open the input screen for configuring the site (see
"myDatanet Server Manual " 805002).
9.2.1.1 Site
Customer
Specifies to which customer the site is assigned
symbol
Assign site to another customer
Name
Site designation (not relevant for the device or data assignment) [2-50 characters]
Device S/N
Serial number of the device that is linked to the site (device assignment!)
Application
Name of the IoT application used to create the site
Tags
List of tags that are already assigned to the site. This assignment can be cancelled by clicking on the
cross next to the title of the tag. The input screen for assigning tags can be opened by clicking on the
plus symbol.
9.2.1.2 Comments
Comments
Free comment field (is also displayed below the device type in the site list)
72
Rev. 01
Chapter 9 User interfaces
9.2.1.3 Control
Note: This configuration section is not visible if this site was created based on an IoT application (see
"myDatanet Server Manual " 805002).
Device logic
type
Off
Device logic deactivated
Pawn
Activates device logic processing and informs the
myDatalogEASY IoTmini that the device logic is a "Pawn script".
Device logic
source
Pawn source
code
Device logic Input window for editing the device logic that is loaded into
the myDatalogEASY IoTmini (see "Device Logic (Pawn)"
on page 83)
Upload a
File upload
compiled script
Selection of the device logic binary file (*.amx) that is
uploaded to the myDatanet server and is loaded into the
myDatalogEASY IoTmini during the next connection. The
file path is only displayed as long as the input screen for
configuring the site has not been closed.
Data descriptor Input window for configuring the Data Descriptor (see "Data Descriptor " on page 185)
9.2.1.4 Configuration 0 - Configuration 9
Note: These configuration sections are only visible if the logical structure of the corresponding configuration
data block was defined using the Data Descriptor (see "Data Descriptor " on page 185). The name of the
configuration section is also defined via the Data Descriptor .
These configuration sections ensure that the parameters from the customer's freely definable, independent
memory blocks can be edited and displayed via the interface of the myDatanet server. For this purpose, the
logical structure of the configuration data blocks must be defined with the help of the Data Descriptor (see
"Data Descriptor " on page 185).
Rev. 01
73
9.2.1.5 Alarm settings
Acknowledgement Standard
Transfer volume
The global server setting is used to determine whether
alarms must be acknowledged automatically or manually.
automatic
Alarms are acknowledged automatically as soon as all of
the messages have been sent. If SMS that have a tariff with
a delivery confirmation function have also been sent,
acknowledgement is provided after delivery confirmation.
manual
Alarms must be acknowledged by the user.
Standard
The setting for the transfer volume alarm is taken from the
global server settings.
off
The transfer volume alarm is deactivated.
individual
The level at which the transfer volume alarm should be
triggered can be entered in the adjacent field in KiB.
Offline alarm after alarm in the event that the device does not report for longer than the set time (00:00
alarm deactivated).
Title user alarm 1
Freely selectable title for user-defined alarm 1. If the user-defined alarm 1 is triggered
by a device connected to the site, the server will use this text to signal the alarm. The
same applies to user-defined alarm 2 and 3.
Title user alarm 2
Freely selectable title for user-defined alarm 2
Title user alarm 3
Freely selectable title for user-defined alarm 3
74
Rev. 01
Chapter 9 User interfaces
9.2.1.6 Basic settings
Time zone
Regional settings (not relevant for raw measurement data as this is stored in
UTC)
Daylight saving time
Configuration for automatic time adjustment
Default report
Standard
The configuration for the time adjustment is adopted by the
global server setting.
Off
Automatic time adjustment deactivated
USA
Predefined setting for the American area
EU
Predefined setting for the European area
Selection of the report that is loaded by clicking on the device link in the maps
Report template
Off
The default graphic is loaded.
"Name of a report"
The selected report is loaded.
Selection of whether the default graphic or a report template to display the data is
used when clicking on the symbol to display the measurement data located in the
site/application list. Only the report templates in which the site/application type of
the first wild card is compatible with the site/application that is currently being
edited are displayed in the dropdown list.
(not assigned)
The default graphic is used to display the measurement
data.
"Name of a report
template"
Name of the report template used to display the
measurement data
Change log configuration Selection of which changes to the configurations should be logged
web api
Changes that were implemented via the server interface or
REST-API are logged.
web device api
Changes that were implemented via the server interface,
by the device itself or the REST-API are logged.
9.2.1.7 FTP export settings
Note: This configuration section is only visible if the "FTP Agent Extended" licence for the myDatanet server
has been enabled.
FTP export profile off
"Name of an
FTP export
profile"
FTP export deactivated
List with the FTP export profiles that were created on the myDatanet
server (for creating an FTP export profile, see "myDatanet Server
Manual " 805002).
Settings of the
selected profile
Shows an overview of the most important parameters of the selected FTP export profile
FTP directory
Makes overwriting the standard directory of the selected FTP export profile possible
[0-100 characters]
Last export
Time stamp of the last FTP export
Rev. 01
75
9.2.2 Device configuration
Note: Several of the configuration fields in the following sub chapters may possibly be hidden depending on the
respective user level. In this case, contact the myDatanet server administrator.
You can reach the input screen for configuring the device by clicking on the serial number in the site list (see
"myDatanet Server Manual " 805002) or by clicking on the device name in the device name list (see
"myDatanet Server Manual " 805002).
9.2.2.1 Comments
Comments
Free comment field (is also displayed below the site name in the measurement instrument list)
9.2.2.2 Measurement instrument
Customer
Name of the customer to whom the measurement instrument is assigned
Tags
List of the tags that are already assigned to the measurement instrument. This
assignment can be cancelled by clicking on the cross next to the title of the tag. The input
screen for assigning the tags is opened by clicking on the plus symbol. This enables
existing tags to be assigned and new tags to be created.
Serial number
Serial number of the instrument
Instrument class
The instrument class of the site and instrument must match for an instrument to be able
to be connected to a site. Once the instrument has been created via the server interface,
the instrument class can only be changed up until the first connection of the instrument to
the server. If an instrument class, that does not match the actual class of the instrument,
is selected when the instrument is created it is automatically corrected during the first
connection.
Telephone
number
Telephone number of the SIM card. The control SMS messages (e.g. wakeup) are sent
to this number. Format: +43555837465
Instrument flags
Additional information regarding the instrument class (for internal use)
Firmware version Current software version installed on the measurement controller
Modem version
Current software version installed on the modem controller
OS version
OS version of the modem
Last connection
In each case, the last time stamp of the affected operation
Last wakeup
Last
disconnection
Last transmission
error
Last Aloha
connection
Wakeup SMS
count
76
Number of wakeup SMS sent to this device since the last connection. This counter is
reset at/during each successfully established connection.
Rev. 01
Chapter 9 User interfaces
Device Logic sync Productive
Development (sync)
The Device Logic on the device and server are synchronised.
The one with the latest time stamp is transferred to the other
one.
Development (no
sync)
The Device Logic on the device and server are not
synchronised.
Firmware update Off
Firmware type
Identification
If the Device Logic installed on the device and saved on the
server do not match, the Device Logic saved on the server is
loaded in to the device.
Firmware update is deactivated.
On
As soon as a new version of the selected firmware type is
available, this is installed immediately.
Even if tag is missing
Firmware is also transferred to the device if the device has not
transmitted the current firmware version to the server (NOT
RECOMMENDED!).
Allow downgrade
Facilitates the installation of an older firmware version than the
one on the device (NOT RECOMMENDED!)
Once
Performs a single firmware update. If no new firmware is
available or the firmware was installed successfully, the
firmware update is automatically switched to "OFF".
Ignore
The firmware update is deactivated and no information is
provided about available firmware updates.
Released
Only firmware versions that have successfully undergone
internal and field testing are installed (this practically eliminates
malfunctions).
Release candidate
Only firmware versions that have successfully undergone
internal testing are installed (malfunctions cannot be excluded).
Beta release
Even firmware versions that have not successfully undergone all
of the internal tests are installed (malfunctions may occur).
String specifying the hardware platform implemented in the device and the
corresponding hardware version (i.e. the rapidM2M module identification).
Hardware version Hardware version of the myDatalogEASY IoTmini
Rev. 01
77
Chapter 10 rapidM2M Studio
Note: The web-based development environment rapidM2M Studio is being developed continuously which can
lead to slight changes to the appearance of the program compared to the screenshots used in this manual.
10.1 General
Access to the web-based development environment rapidM2M Studio is included in the Microtronics Partner
Program, for which you can register free of charge at the following address:
https://partner.microtronics.com
It is a web-based IDE that is designed to support customers with the creation of IoT applications for the
myDatalogEASY IoTmini . This covers the entire development process - from editing the source code, to
testing as part of the creation process to publishing the finished IoT application in the rapidM2M Store . All
elements which make up an IoT application are summarised in a single project. The elements are:
Device logic: intelligence installed locally on the myDatalogEASY IoTmini
Backend logic: intelligence installed on the myDatanet server
l Data descriptor: describes the structure of the data (measurement data, configurations, etc.), that is
exchanged between myDatalogEASY IoTmini , myDatanet server and external systems (e.g. front
ends connected via REST API).
l Portal view: Simple front end that is supplied by the myDatanet server (e.g. for fast prototype
development and/or provision of administrative data)
l
l
In addition to the dashboard for managing the projects, the rapidM2M Studio consists of two main interfaces:
l
l
CODEbed: Editing and compiling the source codes
TESTbed: Testing the IoT application in conjunction with a locally connected device and the
associated back end i.e. the myDatanet server
The sharing function implemented in the rapidM2M Studio enables developers from different disciplines
(firmware programmers, cloud developers, web designers, etc. ) to create an IoT application together as well
as to share projects and libraries with colleagues and the community. The integrated version management
also ensures controlled distribution of updates of an IoT application across the entire chain from the
rapidM2M Studio to the rapidM2M Store to the sites (that were created based on the IoT application) to the
myDatalogEASY IoTmini .
Rev. 01
79
10.2 Prerequisites
Interfaces
1 x USB
Operating system
Windows 7
Windows 10 (recommended)
MacOS 10.12 or higher
Linux (Fedora 32, Ubuntu 20.04, Archlinux 2020.06.01)
Internet
connection
Required
Required disk
space
No installation required
Browser
Google Chrome only
80
Rev. 01
Chapter 11 myDatanet server
Chapter 11 myDatanet server
Note: All of the screenshots show version 47.10 of the myDatanet server using the standard colour scheme.
Newer versions may include minor changes to the appearance of the server.
11.1 Recommended procedure
11.1.1 Creating the site
Detailed instructions on creating a new site are provided in myDatanet Server Manual (805002).
Rev. 01
81
Chapter 12 Device Logic (Pawn)
Chapter 12 Device Logic (Pawn)
12.1 General
The following chapter describes the functionality of the device logic. The programming language used is
"Pawn" (previously SMALL), a scripting language similar to C that runs on embedded systems.
Additional, more detailed information is provided on the developer's website:
http://www.compuphase.com/pawn/pawn.htm.
There are several ways to create a device logic for the myDatalogEASY IoTmini :
Direct entry in the "Device Logic" input field in the "Control" configuration section
Upload of a previously created binary file (*.amx) to the myDatanet server
l Usage of the CODEbed of the web-based development environment rapidM2M Studio
l
l
12.1.1 Direct entry of a device logic
The device logic is entered via the "Control" configuration section (see "Control" on page 73) of the input
screen for configuring the site. "Pawn" must be selected as the "Device Logic Type" so that the
myDatalogEASY IoTmini interprets the commands entered under "Device Logic" as a pawn script.
12.1.2 Uploading a binary file
If the "Upload a compiled device logic" entry was selected via the "Device logic source" list selection in the
"Control" configuration section (see "Control" on page 73) of the input screen for configuring the site, a binary
file that was, for example, previously created via the web-based development environment rapidM2M Studio
(see "rapidM2M Studio " on page 79) can be uploaded to the myDatanet server. This is then loaded into the
myDatalogEASY IoTmini during the next connection. When using this method, "Pawn" must also be selected
as the "Device Logic Type" so that the myDatalogEASY IoTmini interprets the commands as a pawn script.
12.1.3 Using the CODEbed of the web-based development environment rapidM2M
Studio
The CODEbed is one of the two main interfaces of the web-based development environment rapidM2M
Studio . The CODEbed serves to create and compile source codes for all elements (device logic, backend
logic, data descriptor and portal view) of an IoT application. The functional scope of the rapidM2M Studio also
includes transfer of the compiled device logic into the myDatalogEASY IoTmini via a USB connection and
copying of the data descriptor to the development site with which the myDatalogEASY IoTmini is linked.
Rev. 01
83
12.2 Compiler options
Compressing the pawn program code
// The parameter is used to specify which of the sections should be
// compressed
// 0: no compression (default)
// 1: DATA
// 2: DATA and CODE
// 3: DATA, CODE and TABLES
#pragma amxcompress <0-3>
12.3 rapidM2M Device API
12.3.1 Constants
Return codes for general purposes
OK
= 0,
ERROR
= -1,
ERROR_PARAM
= -2, // Parameter error
ERROR_UNKNOWN_HDL
= -3, // Unknown handler, handle or resource error
ERROR_ALREADY_SUBSCRIBED = -4, // Already subscribed service or resource error
ERROR_NOT_SUBSCRIBED
= -5, // Not subscribed service error
ERROR_FATAL
= -6, // Fatal error
ERROR_BAD_HDL
= -7, // Bad handle or resource error
ERROR_BAD_STATE
= -8, // Bad state error
ERROR_PIN_KO
= -9, // Bad PIN state error
ERROR_NO_MORE_HANDLES
= -10, /* The service subscription maximum capacity is
reached */
ERROR_DONE
= -11, /* The required iterative process is now
terminated */
ERROR_OVERFLOW
= -12, /* The required operation has exceeded the
function capabilities */
ERROR_NOT_SUPPORTED
= -13, /* An option, required by the function, is not
enabled on the CPU, the function is not
supported in this configuration */
ERROR_NO_MORE_TIMERS
= -14, /* The function requires a timer subscription,
but no more timer resources are available */
ERROR_NO_MORE_SEMAPHORES = -15, /* The function requires a semaphore allocation,
but there are no more semaphore resources */
ERROR_SERVICE_LOCKED
= -16, /* The function was called from a low or high
level interrupt handler (the function is
forbidden in this case) */
ERROR_MEM
= -100,// error allocating memory
ERROR_SIM_STATE
= -101,// SIM state error
ERROR_MODEM_DISABLED
= -102,// Modem disabled
ERROR_FEATURE_LOCKED
= -103,// feature locked
ERROR_TXITF
= -104,/* tx interface (uplink) not available
(e.g. not opened, currenly closing) */
84
Rev. 01
Chapter 12 Device Logic (Pawn)
12.3.2 Timer, date & time
12.3.2.1 Arrays with symbolic indices
TrM2M_DateTime
Detailed breakdown of the date and time
// year
Year specified relates to the 21st century, i.e. 14 refers to
//
the year 2014
// month
Month
// day
Day
// hour
Hours
// minute
Minutes
// second
Seconds
// DoW
Weekday (0 = Monday ... 6 = Sunday)
// timestamp
Time stamp (seconds since 31.12.1999)
// timestamp256 Fraction of the next started sec. (resolutions 1/256 sec.)
#define TrM2M_DateTime[ .year, .month, .day, .hour, .minute, .second, .DoW,
.timestamp, .timestamp256
]
12.3.2.2 Constants
Time basis flags
Control flags for the rM2M_SetDateTime() function
RM2M_DATETIME_LOCALTIME = 0b00000001, // transferred time in local time
12.3.2.3 Functions
native rM2M_GetTime(&hour=0, &minute=0, &second=0, timestamp=0);
If no time stamp was transferred (timestamp=0), the current system time (in UTC) is converted to
hours/minutes/seconds. Alternatively, the transferred time stamp is converted to
hours/minutes/seconds.
Parameter
hour
Explanation
Variable to store the hours - OPTIONAL
minute
Variable to store the minutes - OPTIONAL
second
Variable to store the seconds - OPTIONAL
timestamp
Time stamp that should be converted
= 0: The current system time (in UTC) is converted.
> 0: The transferred time stamp is converted.
(The time stamp must be specified in seconds since 31.12.1999.)
Return value
Rev. 01
Explanation
l timestamp = 0: Seconds since 31.12.1999 (current system time in UTC)
l timestamp > 0: The transferred time stamp is returned.
85
native rM2M_GetDate(&year=0, &month=0, &day=0, timestamp=0);
If no time stamp was transferred (timestamp=0), the date (year, month, day) is determined for the
current system time (in UTC). Alternatively, the date (year, month, day) is determined for the
transferred time stamp.
Parameter
year
Explanation
Variable to store the year - OPTIONAL
Note: The year specified relates to the 21st century, i.e. the value 14 refers to
the year 2014.
month
Variable to store the month - OPTIONAL
day
Variable to store the day - OPTIONAL
timestamp
Time stamp for which the date should be determined
= 0: The date for the current system time (in UTC) is determined.
> 0: The date for the transferred time stamp is determined.
(The time stamp must be specified in seconds since 31.12.1999.)
Return value
Explanation
l timestamp = 0: Seconds since 31.12.1999 (current system time in UTC)
l timestamp > 0: The transferred time stamp is returned.
native rM2M_GetDateTime(datetime[TrM2M_DateTime]);
Reads the current time (in UTC) and date from the system
Parameter
datetime
Explanation
Structure for storing a detailed breakdown of the date and time (see "TrM2M_
DateTime" in chapter "Arrays with symbolic indices" on page 85)
Explanation
Return value
l
l
86
OK, if successful
ERROR, if an invalid parameter was transferred
Rev. 01
Chapter 12 Device Logic (Pawn)
native rM2M_SetDateTime(datetime[TrM2M_DateTime], flags=0);
Sets the system date and time to the values contained in the transferred structure
Parameter
datetime
flags
Explanation
Structure that contains a detailed breakdown of the date and time (see "TrM2M_
DateTime" in chapter "Arrays with symbolic indices" on page 85).
.timestamp = 0:
The values contained in .year, .month, .day, .hour, .minute
and .second are used to set the date/time.
.timestamp != 0:
The time stamp contained in .timestamp is used to set the
date/time.
Configuration flags for setting the system time - OPTIONAL
Bit0 (RM2M_DATETIME_LOCALTIME):
Return value
must be set if the transferred
structure contains the time in local
time
Explanation
> 0, difference in seconds between the current time and time to be set
l 0, if the difference between the current time and time to be set is less than
5 sec.
l ERROR, if invalid parameters were transferred
l ERROR-1, if the time to be set is more than one day ahead of the current
system time
l
native rM2M_GetTimezoneOffset();
Returns the difference (in seconds) between the system time (UTC) and local time configured for the
site on the myDatanet server. This can be used to determine the local time in the script by adding the
difference to the system time (UTC). The offset value is determined by the myDatanet server in
accordance with the set time zone (including summer/winter time) and is synchronised during every
connection to the device.
Example: Central European time (CET = UTC+1) is used for the site -> Offset = 3600 sec.
Explanation
Return value
Offset value in seconds
native rM2M_DoW(timestamp);
Calculates the weekday from a given timestamp
Parameter
timestamp
Timestamp of the day in question
Return value
Explanation
Weekday, 0=Monday ... 6=Sunday
Rev. 01
Explanation
87
native rM2M_TimerAdd(funcidx);
Generates a new 1s timer
Parameter
funcidx
Explanation
Index of the public function that should be called up following expiry of the timer
Type of function: public func();
Explanation
Return value
OK, if successful
ERROR if no valid index was transferred, in the event of an internal error or
if no further timers can be created (maximum number reached)
l < OK, if another error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84).
l
l
native rM2M_TimerRemove(funcidx);
Removes a 1s timer
Parameter
funcidx
Explanation
Index of the public function of the timer that should be removed
Type of function: public func();
Explanation
Return value
OK, if successful
ERROR, if no valid index was transferred or in the event of an internal error
l < OK, if another error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84).
l
l
88
Rev. 01
Chapter 12 Device Logic (Pawn)
native rM2M_TimerAddExt(funcidx, bool:cyclic, time);
Generates a new ms timer
Parameter
funcidx
Explanation
Index of the public function that should be called up following expiry of the timer
Type of function: public func();
cyclic
Setting for the behaviour following expiry of the timer interval:
true: The timer must be restarted following expiry of the interval.
false: The timer is stopped following expiry of the interval.
time
Timer interval in milliseconds (max. 60,000 ms)
Note: By setting the interval to 0ms, a timer can be generated for which the call
back function is called up immediately after the current code block (e.g. main
function) is executed. However, only single shot timers (i.e. the timer is stopped
upon expiry of an interval) with an interval of 0ms may be initialised.
Explanation
Return value
OK, if successful
ERROR, if one of the following errors occurs
l No valid index was transferred.
l An interval of 0ms was specified and the timer should be restarted
automatically upon expiry of the timeout (i.e. cyclical 0ms timer).
l Internal error
l No additional timers can be created (maximum number reached).
l < OK, if another error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84).
l
l
native rM2M_TimerRemoveExt(funcidx);
Removes a ms timer
Parameter
funcidx
Explanation
Index of the public function of the timer that should be removed
Type of function: public func();
Explanation
Return value
OK, if successful
ERROR, if no valid index was transferred or in the event of an internal error
l < OK, if another error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84).
l
l
Rev. 01
89
12.3.3 Uplink
12.3.3.1 Constants
Configuration flags for the rM2M_CfgInit() function
RM2M_CFG_VOLATILE
= 0b00000001, // volatile storage (RAM)
12.3.3.2 Callback functions
public func(const data[], len, timestamp);
Function to be provided by the script developer, that is called once a data record has been read (using
the "rM2M_ReadData()" function) from the internal flash memory.
Parameter
data
Explanation
Array that contains the data of the read data record
len
Length of the data area of the read data record in bytes (max. 1024 Byte )
timestamp
Time stamp of the data record (in UTC)
public func(cfg);
Function to be provided by the script developer, that is called if one of the configuration memory blocks
has changed
Parameter
cfg
90
Explanation
Number of the changed configuration memory block starting with 0 for the first
memory block
Rev. 01
Chapter 12 Device Logic (Pawn)
12.3.3.3 Functions
native rM2M_LiveData(const data{}, len);
Transmits a data record as live data to the server. Calling this function is only permissible if the device is
in "online" mode and an active connection to the server is established. Use the "rM2M_Pack", "rM2M_
SetPacked" or "rM2M_SetPackedB" functions to generate the data area.
Parameter
data
Explanation
Array that contains the live data to be transferred
Important note: The structure of the live data must be identical to that of
the measurement data saved in the internal flash using the "rM2M_
RecData()" function.
len
Return value
Number of bytes to be transferred (max. 1024 Byte )
Explanation
OK, if successful
l ERROR, if an error occurs (e.g. the server does not support receipt of live
data.)
l
native rM2M_RecData(timestamp, const data{}, len);
Saves a data record in the internal flash memory. Use the "rM2M_Pack", "rM2M_SetPacked" or
"rM2M_SetPackedB" functions to generate the data area.
Parameter
timestamp
Explanation
Time stamp that should be used for the recording
= 0: The current system time is used as the time stamp.
> 0: The transferred time stamp is used.
(The time stamp must be specified in seconds since 31.12.1999)
data
Array that contains the data to be saved
len
Number of bytes to be saved (max. 1024 Byte )
Explanation
Return value
OK, if successful
-2, if data storage is not currently possible as the internal memory is being
reorganised. The data must be temporarily saved in the script and stored
again at a later date.
l ERROR, if one of the following errors occurs
l Memory area (data{}, len) is invalid.
l More than 10 calls during one script run
l Number of bytes to be saved > 1024 Byte
l FLASH write process not successful
l The time stamp transfer parameter is more than 5 minutes in the
future
l < OK, if another error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84).
l
l
Rev. 01
91
native rM2M_ReadData(recidx, funcidx);
Reads out a data record saved in the internal flash and then calls up the function for which the index
was transferred.
Parameter
recidx
Explanation
Index of the data record to be read (-1 = last/current data record, -2 = penultimate
data record, .... )
funcidx
Index of the public function that should be called once the data record has been
read from the internal flash memory.
Type of function: public func(const data[], len, timestamp);
Return value
Explanation
l OK, if the read process has been started
l ERROR, if an error occurs
native rM2M_CfgInit(cfg, flags);
Sets the configuration for a configuration memory block. Calling the function is only necessary if one of
the configuration flags should be set.
Parameter
cfg
Explanation
Number of the configuration memory block starting with 0 for the first memory
block. The device comprises 10 independent memory blocks.
flags
Configuration flags to be set/deleted
Bit0: Type of storage
0 (default) = stored in FLASH in non-volatile manner
RM2M_CFG_VOLATILE = saved in RAM in volatile manner
Explanation
Return value
l
l
OK, if successful
< OK, if an error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84)
Note: Additional explanation on the type of storage:
If Bit 0 was not set (default), the non-volatile storage of the configuration memory block in the FLASH is
initiated when the "rM2M_CfgWrite" function is called.
If Bit0 was set (Bit0 = RM2M_CFG_VOLATILE), the configuration memory block is saved in the RAM in
a volatile manner when the "rM2M_CfgWrite" function is called. This option is recommended if the data
in the configuration memory block changes frequently as this will reduce the number of flash write
cycles. The "rM2M_CfgFlush" function must be called so that the configuration memory block is saved
in a non-volatile manner in the FLASH.
92
Rev. 01
Chapter 12 Device Logic (Pawn)
native rM2M_CfgWrite(cfg, pos, const data{}, size);
Saves the transferred data block at the specified position in a configuration memory block. Note that the
configuration memory block is either saved in the RAM in a volatile manner (Bit0 = RM2M_CFG_
VOLATILE) or in the FLASH in a non-volatile manner (Bit0 = 0, default) depending on the type of
storage selected via the "rM2M_CfgInit" function. The function is also passed which of the 10 available
memory blocks in the internal flash memory should be used. Use the "rM2M_Pack", "rM2M_
SetPacked" or "rM2M_SetPackedB" functions to generate the data block that should be saved. The
time stamp is updated, so that the configuration memory block is automatically synchronised with the
myDatanet server during the next connection.
Parameter
cfg
Explanation
Number of the configuration memory block starting with 0 for the first memory
block. The device comprises 10 independent memory blocks.
pos
Byte offset within the configuration memory block to determine the position where
the data should be written
data
Array that contains the data that should be written in the configuration memory
block
size
Number of bytes that should be written in the configuration memory block
Explanation
Return value
OK, if successful
ERROR_MEM, if enough temporary memory (RAM) is not currently
available. (can occur if "RAM in a volatile manner" is selected as the type of
storage for several configuration memory blocks)
l < OK, if another error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84).
l
l
native rM2M_CfgFlush(cfg);
Saves the configuration memory block for which the number was transferred in the FLASH in a nonvolatile manner. Calling the function is only necessary if "volatile in RAM (Bit0 = RM2M_CFG_
VOLATILE)" was selected as the type of storage for the relevant configuration memory block via the
"rM2M_CfgInit" function.
Parameter
cfg
Explanation
Number of the configuration memory block starting with 0 for the first memory
block. The device comprises 10 independent memory blocks.
Explanation
Return value
l
l
Rev. 01
OK, if successful
< OK, if an error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84)
93
native rM2M_CfgRead(cfg, pos, data{}, size);
Reads a data block from the specified position in a configuration memory block. The function is also
informed which of the 10 available memory blocks in the internal flash memory should be read. Use the
"rM2M_Pack", "rM2M_GetPacked" or "rM2M_GetPackedB" functions to unpack the read data.
Parameter
cfg
Explanation
Number of the configuration memory block starting with 0 for the first memory
block. The device comprises 10 independent memory blocks.
pos
Byte offset within the configuration memory block to determine the position from
which the data should be read
data
Array to store the data to be read
size
Number of bytes that should be read from the configuration memory block
Return value
Explanation
Size of the memory used in the configuration memory block
l ERROR_MEM, if enough temporary memory (RAM) is not currently
available. (can occur if "RAM in a volatile manner" is selected as the type of
storage for several configuration memory blocks)
l < OK, if another error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84).
l
native rM2M_CfgDelete(cfg);
Deletes all of the data of the transferred configuration memory block
Parameter
cfg
Explanation
Number of the configuration memory block starting with 0 for the first memory
block. The device comprises 10 independent memory blocks.
Explanation
Return value
OK, if successful
ERROR_MEM, if enough temporary memory (RAM) is not currently
available. (can occur if "RAM in a volatile manner" is selected as the type of
storage for several configuration memory blocks)
l < OK, if another error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84).
l
l
94
Rev. 01
Chapter 12 Device Logic (Pawn)
native rM2M_CfgOnChg(funcidx);
Specifies the function that should be called if one of the configuration memory blocks has changed
Parameter
funcidx
Explanation
Index of the public function that should be called if the configuration has changed
Type of function: public func(cfg);
Explanation
Return value
OK, if successful
ERROR, if no valid index of a public function was transferred
l < OK, if another error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84).
l
l
12.3.4 System
Note: You require the following include file to be able to use the functions in this chapter: #include
<easyV3>
12.3.4.1 Arrays with symbolic indices
TEasyV3_SysValue
Internal measurement values
// Temp
// RH
Internal housing temperature in [0.1°C]
Humidity in the housing in [0.1% rH]
#define TEasyV3_SysValue[.Temp, .RH]
12.3.4.2 Constants
Numbers of the universal inputs
UI_CHANNEL1
UI_CHANNEL2
UI_CHANNEL3
UI_CHANNEL4
= 0,
= 1,
= 2,
= 3,
// Universal input 1
// Universal input 2
// Universal input 3
// Universal input 4
//Number of universal inputs, with which the myDatalogEASY IoTmini is equipped
UI_NUM_CHANNELS = 4,
Rev. 01
95
Numbers of the temperature sensor interfaces
TEMP_CHANNEL1
= 0,
// PT100/1000 interface 1
//Number of temperature sensor interfaces, with which the myDatalogEASY IoTmini
is
//equipped
TEMP_NUM_CHANNELS = 1,
Configuration of the external temperature measurement (PT100/1000)
Configuration options for the Temp_Init() function
TEMP_MODE_SINGLE_CONV = 0,
TEMP_MODE_CONT_CONV
= 1,
// single conversion mode
// continuous conversion mode
Identifications of the modules implemented in the myDatalogEASY IoTmini
These are used by the functions for updating the firmware of the modules.
#define MODFW_LORA
#define MODFW_BLE
96
"CMWX1ZZABZ"
"NINA-B11X"
// LoRa module
// Bluetooth low energy module
Rev. 01
Chapter 12 Device Logic (Pawn)
12.3.4.3 Functions
native Temp_Init(temp, mode);
The temperature is only measured once after this function is called if single conversion mode has been
activated (mode = TEMP_MODE_SINGLE_CONV). The measurement value can be read out by the
"Temp_GetValue" function until the PT100/1000 interface is closed by the "Temp_Close" function.
The temperature is measured at 320ms intervals after this function is called if continuous conversion
mode has been activated (mode = TEMP_MODE_CONT_CONV). The "Temp_GetValue" function
always supplies the last valid temperature value until the PT100/1000 interface is closed by the "Temp_
Close" function.
Parameter
temp
Explanation
Number of the PT100/1000 interface; is always 0 for the
myDatalogEASY IoTmini
mode
TEMP_MODE_SINGLE_
CONV :
The temperature is only measured once after
the "Temp_Init" function is called.
TEMP_MODE_CONT_CONV : The temperature is measured continuously at
320ms intervals after the "Temp_Init" function
is called.
Return value
Explanation
Time in [ms] required to measure the temperature
l ERROR_FEATURE_LOCKED, if the specified interface on the device is
not released
l ERROR, if an invalid parameter was transferred
l
Note: The energy consumption in continuous conversion mode is significantly higher than in single
conversion mode. The lowest level of energy consumption is only achieved once the PT100/1000
interface is closed via the "Temp_Close" function. This means that even if the PT100/1000 interface
was initialised in single conversion mode, it should be closed as soon as the measurement value is read
out.
native Temp_Close(temp);
Closes the PT100/1000 interface. This switches the temperature module to the mode with the lowest
energy consumption.
Parameter
temp
Explanation
Number of the PT100/1000 interface; is always 0 on the
myDatalogEASY IoTmini
Explanation
Return value
OK, if successful
ERROR_FEATURE_LOCKED, if the specified interface on the device is
not released
l < OK, if another error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84).
l
l
Rev. 01
97
native Temp_GetValue(temp, &value);
Reads the temperature measurement value for the specified PT100/1000 interface from the
temperature module
Parameter
temp
Explanation
Number of the PT100/1000 interface; is always 0 on the
myDatalogEASY IoTmini
value
Variable to store the temperature measurement value to be read out. The
temperature measurement value is saved in the temperature module in [0.1°C].
Explanation
Return value
OK, if successful
ERROR_FEATURE_LOCKED, if the specified interface on the device is
not released
l < OK, if another error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84).
l
l
native EasyV3_GetSysValues(values[TEasyV3_SysValue], len=sizeof values);
Reads the last valid values for the "Internal housing temperature" and "Air humidity in the housing" from
the system. The interval for determining these values is 10sec. and cannot be changed.
Parameter
values
Explanation
Structure for storing the measurement values (see "TEasyV3_SysValue" in
chapter "Arrays with symbolic indices" on page 95)
len
Size (in cells) of the structure to store the measurement values - OPTIONAL
Return value
98
Explanation
Size (in cells) of the structure used to store the measurement values
l ERROR, if one of the following errors occurs
l Address and/or length of the values structure is invalid (outside the
script data memory).
l One of the measurement values is invalid.
l
Rev. 01
Chapter 12 Device Logic (Pawn)
12.3.5 Encoding
12.3.5.1 Constants
Configuration flags for the rM2M_Pack() function
RM2M_PACK_GET
RM2M_PACK_BE
RM2M_PACK_U8
RM2M_PACK_S8
RM2M_PACK_U16
RM2M_PACK_S16
RM2M_PACK_U32
RM2M_PACK_S32
RM2M_PACK_F32
Rev. 01
= 0b00000001, // Value should be read (get packed)
= 0b00000010, // Use "Big endian" format
= 0b00010000, // 8-bit unsigned
= 0b10010000, // 8-bit signed
= 0b00100000, // 16-bit unsigned
= 0b10100000, // 16-bit signed
= 0b01000000, // 32-bit unsigned
= 0b11000000, // 32-bit signed
= 0b01000000, // 32-bit float
99
12.3.5.2 Functions
native rM2M_SetPacked(data{}, pos, &{Float,Fixed,_}:value, size=4, bool:bigendian=false);
Writes the transferred value to a specified position in an array
Important note: Although this function will still be supported for the purpose of downward
compatibility, it should no longer be used for new projects as the unsigned data types might lead
to problems. The „rM2M_Pack()" function should be used as an alternative.
Parameter
data
Explanation
Array that should be used as a data area for a data record or a configuration
pos
Byte offset within the array to determine the position where the value should be
written
value
Value that should be written in the array
size
Number of bytes that should be used for the value to be written
bigendian
Settings for the byte sequence that should be used when writing the value:
true: "Big endian" is used
false: "Little endian" is used
Return value
Explanation
OK, if successful
l < OK, if an error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84)
l
Note: Additional explanation on the byte sequence:
In the following example, the whole number 439.041.101 is saved as a 32-bit integer value from memory
address 10000.
100
Addresses
10000
1A
Big endian
Dez
Binary
26
00011010
10001
2B
43
00101011
3C
60
00111100
10002
3C
60
00111100
2B
43
00101011
10003
4D
77
01001101
1A
26
00011010
Hex
4D
Little endian
Dez
Binary
77
01001101
Hex
Rev. 01
Chapter 12 Device Logic (Pawn)
native rM2M_SetPackedB(data{}, pos, const block[], size);
Writes the transferred data block to the specified position in an array
Parameter
data
Explanation
Array that should be used as a data area for a data record or a configuration
pos
Byte offset within the array to determine the position where the data block should
be written
block
Data block that should be written in the array
size
Number of bytes that should be written in the array by the data block
Explanation
Return value
l
l
Rev. 01
OK, if successful
< OK, if an error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84)
101
native rM2M_GetPacked(const data{}, pos, &{Float,Fixed,_}:value, size=4, bool:bigendian=false);
Supplies the value that is located at the specified position in an array
Important note: Although this function will still be supported for the purpose of downward
compatibility, it should no longer be used for new projects as the unsigned data types might lead
to problems. The „rM2M_Pack()" function should be used as an alternative.
Parameter
data
Explanation
Array that should be used as a data area for a data record or a configuration
pos
Byte offset within the array to determine the position from which the data should
be read
value
Variable to store the data to be read
size
Number of bytes that should be read
bigendian
Specifies how the packed data must be interpreted:
true: The data is saved in "Big endian" format in the array.
false: The data is saved in "Little endian" format in the array.
Explanation
Return value
l
l
OK, if successful
< OK, if an error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84)
Note: Additional explanation on the byte sequence:
In the following example, the whole number 439.041.101 is saved as a 32-bit integer value from memory
address 10000.
102
Addresses
10000
1A
Big endian
Dez
Binary
26
00011010
10001
2B
43
00101011
3C
60
00111100
10002
3C
60
00111100
2B
43
00101011
10003
4D
77
01001101
1A
26
00011010
Hex
4D
Little endian
Dez
Binary
77
01001101
Hex
Rev. 01
Chapter 12 Device Logic (Pawn)
native rM2M_GetPackedB(const data{}, pos, block[], size);
Reads a data block that is located at the specified position in an array
Parameter
data
Explanation
Array that should be used as a data area for a data record or a configuration
pos
Byte offset within the array to determine the position from which the data should
be read
block
Array to store the data to be read
size
Number of bytes that should be read
Explanation
Return value
l
l
Rev. 01
OK, if successful
< OK, if an error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84)
103
native rM2M_Pack(const data{}, pos, &{Float,Fixed,_}:value, type);
Function to access packed data. If the Bit0 (RM2M_PACK_GET) of the "type" parameter was set, the
function returns the value that is located at the specified position in the array. Otherwise the function
writes the transferred value to the specified position in the array.
Parameter
data
Explanation
Array with the packed content
Set packed: Array to which the value should be written
Get packed: Array from which the value should be read
pos
Byte offset within the array
Set packed: Position to which the value should be written
Get packed: Position from which the value should be read
value
Set packed: Value that should be written in the array
Get packed: Value that should be read from the array
type
Configuration flags for the function
Bit0: Select "Set packed" / "Get packed"
0 = value should be written
1 = value should be read
Bit1: Byte order
0 = "Little endian" format
1 = "Big endian" format
Bit2...3
reserved for extensions
Bit4...7: Data type
1 = 8-bit unsigned
2 = 16-bit unsigned
4 = 32-bit unsigned / 32-bit float
9 = 8-bit signed
10 = 16-bit signed
12 = 32-bit signed
Note: You can also use the predefined constants for this parameter (see
"Configuration flags for the rM2M_Pack() function" in chapter "Constants" on
page 99). The constants can also be combined using the "or" link.
Explanation
Return value
l
l
104
OK, if successful
< OK, if an error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84)
Rev. 01
Chapter 12 Device Logic (Pawn)
12.3.6 RS232, RS485
12.3.6.1 Constants
Configuration of the RS232 interface
Configuration flags for the RS232_Init() function
RS232_1_STOPBIT
RS232_2_STOPBIT
RS232_PARITY_NONE
RS232_PARITY_ODD
RS232_PARITY_EVEN
RS232_7_DATABIT
RS232_8_DATABIT
RS232_FLOW_NONE
RS232_FLOW_RTSCTS
RS232_FULL_DUPLEX
RS232_HALF_DUPLEX
= 0b0000000000000001, // 1 stop bit
= 0b0000000000000010, // 2 stop bit
= 0b0000000000000000, // no parity
= 0b0000000000000100, // odd parity
= 0b0000000000001000, // even parity
= 0b0000000000000000, // 7 data bits
= 0b0000000000010000, // 8 data bits
= 0b0000000000000000, // no flow control
= 0b0000000001000000, // RTS/CTS hand shake
= 0b0000000000000000, // full duplex mode
= 0b0000000100000000, // half duplex mode
Configuration of the RS485 interface
Configuration flags for the RS485_Init() function
RS485_1_STOPBIT
RS485_2_STOPBIT
RS485_PARITY_NONE
RS485_PARITY_ODD
RS485_PARITY_EVEN
RS485_7_DATABIT
RS485_8_DATABIT
RS485_FLOW_NONE
RS485_FLOW_RTSCTS
RS485_HALF_DUPLEX
RS485_FULL_DUPLEX
RS485_120_OHM_NONE
RS485_120_OHM_ACT
= 0b0000000000000001, // 1 stop bit
= 0b0000000000000010, // 2 stop bit
= 0b0000000000000000, // no parity
= 0b0000000000000100, // odd parity
= 0b0000000000001000, // even parity
= 0b0000000000000000, // 7 data bits
= 0b0000000000010000, // 8 data bits
= 0b0000000000000000, // no flow control
= 0b0000000001000000, // RTS/CTS hand shake
= 0b0000000000000000, // half duplex mode
= 0b0000000100000000, // full duplex mode
= 0b0000000000000000, // no load resistance
= 0b0000001000000000, // 120Ω load resistance
12.3.6.2 Callback functions
public func(const data{}, len);
Function to be provided by the script developer, that is called when characters are received via the
RS232 interface
Parameter
data
Explanation
Array that contains the received data
len
Number of received bytes
Rev. 01
105
public func(const data{}, len);
Function to be provided by the script developer, that is called when characters are received via the
RS485 interface
106
Parameter
data
Explanation
Array that contains the received data
len
Number of received bytes
Rev. 01
Chapter 12 Device Logic (Pawn)
12.3.6.3 Functions
native RS232_Init(rs232, baudrate, mode, funcidx);
Initialises the RS232 interface
Parameter
rs232
Explanation
Number of the RS232 interface; is always 0 for the myDatalogEASY IoTmini
Note: You can also use the predefined constant "RS232_ITF1" for this
parameter.
baudrate
Baud rate to be used. Observe the valid limits for the device being used (see
"Technical details about the RS232 interface" on page 57).
mode
Bit 0...1
1 = 1 stop bit
2 = 2 stop bits
Bit 2...3
0 = no parity
1 = uneven parity
2 = even parity
Bit 4...5
0 = 7 data bits
1 = 8 data bits
Bit 6...7
0 = no flow control
1 = RTS/CTS handshake
Bit 8
0 = full duplex mode
1 = half duplex mode
Note: You can also use the predefined constants for this parameter (see
"Configuration of the RS232 interface" in the chapter "Constants" on page 105).
The constants can also be combined using the "or" conjunction.
funcidx
Index of the public function for the RS232 character receipt
Type of function: public func(const data{}, len);
Explanation
Return value
OK, if successful
ERROR_FEATURE_LOCKED, if the specified interface on the device is
not released
l < OK, if another error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84).
l
l
Rev. 01
107
native RS232_Close(rs232);
Closes the RS232 interface
Parameter
rs232
Explanation
Number of the RS232 interface; is always 0 for the myDatalogEASY IoTmini
Note: You can also use the predefined constant "RS232_ITF1" for this
parameter.
Explanation
Return value
OK, if successful
ERROR_FEATURE_LOCKED, if the specified interface on the device is
not released
l < OK, if another error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84).
l
l
native RS232_Write(rs232, const data{}, len);
Sends data via the specified RS232 interface
Parameter
rs232
Explanation
Number of the RS232 interface; is always 0 on the myDatalogEASY IoTmini
Note: You can also use the predefined constant "RS232_ITF1" for this
parameter.
data
Array that contains the data to be sent
len
Number of bytes to be sent
Return value
l
Explanation
Number of processed bytes, if successful
Note: If the number of processed bytes deviates from the passed number
of bytes to be sent, the RS232_Write() function must be called again.
However, now only the data that could not be processed in the previous
function call needs to be passed here.
ERROR_FEATURE_LOCKED, if the specified interface on the device is
not released
l < OK, if another error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84).
l
108
Rev. 01
Chapter 12 Device Logic (Pawn)
native RS232_Setbuf(rs232, rxbuf{}, rxlen, txbuf{}, txlen);
Provides the firmware with one buffer for sending and one for receiving characters via the RS232
interface from the RAM area reserved for the Device Logic. When this function is called, the system
switches from the 256 byte buffers integrated in the firmware to the transferred buffers.
Important note: If necessary, this function may need to be called before the initialisation of the
RS232 interface via the "RS232_Init()" function.
Parameter
rs232
Explanation
Number of the RS232 interface; is always 0 on the myDatalogEASY IoTmini
Note: You can also use the predefined constant "RS232_ITF1" for this
parameter.
rxbuf
Static byte array that should be used as a buffer to receive characters via the
RS232 interface
rxlen
Size of the receiving buffer in byte
Note: If the function is called up again and the size is set to "0" during the
process, then the system switches back to the integrated buffer (256 bytes). The
transferred static byte array can then be used by the script again.
txbuf
Static byte array that should be used as a buffer to send characters via the RS232
interface
txlen
Size of the sending buffer in byte
Note: If the function is called up again and the size is set to "0" during the
process, then the system switches back to the integrated buffer (256 bytes). The
transferred static byte array can then be used by the script again.
Explanation
Return value
l
l
Rev. 01
OK, if successful
< OK, if an error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84)
109
native RS485_Init(rs485, baudrate, mode, funcidx);
Initialises the RS485 interface
Parameter
rs485
Explanation
Number of the RS485 interface; is always 0 for the myDatalogEASY IoTmini
Note: You can also use the predefined constant "RS485_ITF1" for this
parameter.
baudrate
Baud rate to be used. Observe the valid limits for the device being used (see
"Technical details about the RS485 interface" on page 56).
mode
Bit 0...1
1 = 1 stop bit
2 = 2 stop bits
Bit 2...3
0 = no parity
1 = uneven parity
2 = even parity
Bit 4...5
0 = 7 data bits
1 = 8 data bits
Bit 6...7
0 = no flow control
1 = RTS/CTS handshake
Bit 8
0 = half duplex mode
1 = full duplex mode
Bit 9
0 = no load resistance
1 = 120Ω load resistance
Note: You can also use the predefined constants for this parameter (see
"Configuration of the RS485 interface" in the chapter "Constants" on page 105).
The constants can also be combined using the "or" conjunction.
funcidx
Index of the public function for the RS485 character receipt
Type of function: public func(const data{}, len);
Explanation
Return value
OK, if successful
ERROR_FEATURE_LOCKED, if the specified interface on the device is
not released
l < OK, if another error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84).
l
l
110
Rev. 01
Chapter 12 Device Logic (Pawn)
native RS485_Close(rs485);
Closes the RS485 interface
Parameter
rs485
Explanation
Number of the RS485 interface; is always 0 for the myDatalogEASY IoTmini
Note: You can also use the predefined constant "RS485_ITF1" for this
parameter.
Explanation
Return value
OK, if successful
ERROR_FEATURE_LOCKED, if the specified interface on the device is
not released
l < OK, if another error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84).
l
l
native RS485_Write(rs485, const data{}, len);
Sends data via the specified RS485 interface
Parameter
rs485
Explanation
Number of the RS485 interface; is always 0 for the myDatalogEASY IoTmini
Note: You can also use the predefined constant "RS485_ITF1" for this
parameter.
data
Array that contains the data to be sent
len
Number of bytes to be sent
Return value
l
Explanation
Number of processed bytes, if successful
Note: If the number of processed bytes deviates from the transferred
number of bytes to be sent, then the RS485_Write() function must be
called again. However, now only the data that could not be processed in
the previous function call needs to be transferred here.
ERROR_FEATURE_LOCKED, if the specified interface on the device is
not released
l < OK, if another error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84).
l
Rev. 01
111
native RS485_Setbuf(rs485, rxbuf{}, rxlen, txbuf{}, txlen);
Provides the firmware with one buffer for sending and one for receiving characters via the RS485
interface from the RAM area reserved for the Device Logic. When this function is called, the system
switches from the 256 byte buffers integrated in the firmware to the transferred buffers.
Important note: If necessary, this function may need to be called before the initialisation of the
RS485 interface via the "RS485_Init()" function.
Parameter
rs485
Explanation
Number of the RS485 interface; is always 0 for the myDatalogEASY IoTmini
Note: You can also use the predefined constant "RS485_ITF1" for this
parameter.
rxbuf
Static byte array that should be used as a buffer to receive characters via the
R485 interface
rxlen
Size of the receiving buffer in byte
Note: If the function is called up again and the size is set to "0" during the
process, then the system switches back to the integrated buffer (256 bytes). The
transferred static byte array can then be used by the script again.
txbuf
Static byte array that should be used as a buffer to send characters via the RS485
interface
txlen
Size of the sending buffer in byte
Note: If the function is called up again and the size is set to "0" during the
process, then the system switches back to the integrated buffer (256 bytes). The
transferred static byte array can then be used by the script again.
Explanation
Return value
l
l
112
OK, if successful
< OK, if an error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84)
Rev. 01
Chapter 12 Device Logic (Pawn)
12.3.7 LoRa
12.3.7.1 Constants
Configuration of the UART interface that is connected to the LoRa module
Configuration flags for the LoRa_Init() function
LORA_1_STOPBIT
LORA_2_STOPBIT
LORA_PARITY_NONE
LORA_PARITY_ODD
LORA_PARITY_EVEN
LORA_7_DATABIT
LORA_8_DATABIT
LORA_FLOW_NONE
LORA_FLOW_RTSCTS
LORA_FULL_DUPLEX
LORA_HALF_DUPLEX
= 0b0000000000000001, // 1 Stop bit
= 0b0000000000000010, // 2 Stop bit
= 0b0000000000000000, // no parity
= 0b0000000000000100, // odd parity
= 0b0000000000001000, // even parity
= 0b0000000000000000, // 7 Data bits
= 0b0000000000010000, // 8 Data bits
= 0b0000000000000000, // no flow control
= 0b0000000001000000, // RTS/CTS hand shake
= 0b0000000000000000, // full duplex mode
= 0b0000000100000000, // half duplex mode
12.3.7.2 Callback functions
public func(const data{}, len);
Function to be provided by the script developer, that is called when characters are received via the
RS232 interface connected to the LoRa module
Parameter
data
Explanation
Array that contains the received data
len
Number of received bytes
Rev. 01
113
12.3.7.3 Functions
native LoRa_Init(LoRa, baudrate, mode, funcidx);
Initialises the UART interface that is connected to the LoRa module
Parameter
LoRa
Explanation
Number of the UART interface that is connected to the LoRa module; for the
myDatalogEASY IoTmini always 0
baudrate
Baud rate to be used
mode
Bit 0...1
1 = 1 stop bit
2 = 2 stop bits
Bit 2...3
0 = no parity
1 = uneven parity
2 = even parity
Bit 4...5
0 = 7 data bits
1 = 8 data bits
Bit 6...7
0 = no flow control
1 = RTS/CTS handshake
Bit 8
0 = full duplex mode
1 = half duplex mode
Note: You can also use the predefined constants for this parameter (see
"Configuration of the UART interface that is connected to the LoRa module" in
chapter "Constants" on page 113). The constants can also be combined using
the "or" conjunction.
funcidx
Index of the public function for receiving characters on the UART interface that is
connected to the LoRa module
Type of function: public func(const data{}, len);
Explanation
Return value
OK, if successful
ERROR_FEATURE_LOCKED if data transmission via LoRaWAN is not
activated on the device
l < OK, if another error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84).
l
l
114
Rev. 01
Chapter 12 Device Logic (Pawn)
native LoRa_Close(LoRa);
Closes the UART interface that is connected to the LoRa module
Parameter
LoRa
Explanation
Number of the UART interface that is connected to the LoRa module; for the
myDatalogEASY IoTmini always 0
Explanation
Return value
OK, if successful
ERROR_FEATURE_LOCKED if data transmission via LoRaWAN is not
activated on the device
l < OK, if another error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84).
l
l
native LoRa_Write(LoRa, const data{}, len);
Sends data via the specified UART interface
Parameter
LoRa
Explanation
Number of the UART interface that is connected to the LoRa module; for the
myDatalogEASY IoTmini always 0
data
Array that contains the data to be sent
len
Number of bytes to be sent
Return value
l
Explanation
Number of processed bytes, if successful
Note: If the number of processed bytes deviates from the transferred
number of bytes to be sent, then the LoRa_Write() function must be
called again. However, now only the data that could not be processed in
the previous function call needs to be passed here.
ERROR_FEATURE_LOCKED if data transmission via LoRaWAN is not
activated on the device
l < OK, if another error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84).
l
Rev. 01
115
native LoRa_Setbuf(LoRa, rxbuf{}, rxlen, txbuf{}, txlen);
Provides the firmware with one buffer for sending and one for receiving characters via the UART
interface, that is connected to the LoRa module, from the RAM area reserved for the device logic.
When this function is called, the system switches from the 128 byte buffers integrated in the firmware to
the transferred buffers.
Important note: If required, this function must be called before the UART interface is initialised
via the "LoRa_Init()" function.
Parameter
LoRa
Explanation
Number of the UART interface that is connected to the LoRa module; for the
myDatalogEASY IoTmini always 0
rxbuf
Static byte array that should be used as a buffer to receive characters via the
UART interface
rxlen
Size of the receiving buffer in byte
Note: If the function is called up again and the size is set to "0" during the
process, then the system switches back to the integrated buffer (128 bytes). The
transferred static byte array can then be used by the script again.
txbuf
Static byte array that should be used as a buffer to send characters via the UART
interface
txlen
Size of the sending buffer in byte
Note: If the function is called up again and the size is set to "0" during the
process, then the system switches back to the integrated buffer (128 bytes). The
transferred static byte array can then be used by the script again.
Explanation
Return value
l
l
116
OK, if successful
< OK, if an error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84)
Rev. 01
Chapter 12 Device Logic (Pawn)
12.3.8 Registry
12.3.8.1 Constants
Indices of the registration memory blocks
that can be accessed via the "rM2M_RegGetString()", "rM2M_RegGetValue()", "rM2M_
RegSetString()", "rM2M_RegSetValue()", "rM2M_RegDelValue()" and "rM2M_RegDelKey()"
functions. Detailed information on the registration memory blocks is provided in chapter "Registration
memory blocks" on page 32.
//System-specific data
RM2M_REG_SYS_OTP
= 0, // once during production (recommended)
RM2M_REG_SYS_FLASH = 1, // can be changed during operation (not via script)
//Application-specific data
RM2M_REG_APP_OTP
= 2, // once during production (recommended)
RM2M_REG_APP_FLASH = 3, // can be changed during operation (also via script)
//Application-specific, volatile data
RM2M_REG_APP_STATE = 4, // can be changed during operation (only via the script)
//Number of registration memory blocks
RM2M_REG_NUM_REGS = 5,
Error codes for the registration memory block access operations
RM2M_REG_ERROR_TOKENMEM
RM2M_REG_ERROR_INVAL
RM2M_REG_ERROR_PART
= -101,
= -102,
= -103,
RM2M_REG_ERROR_NOMEM
= -200,
RM2M_REG_ERROR_NUMTOKENS = -201,
RM2M_REG_ERROR_PAIR
RM2M_REG_ERROR_NOTOKENS
RM2M_REG_ERROR_NOTFOUND
RM2M_REG_ERROR_TYPE
RM2M_REG_ERROR_PARAM
RM2M_REG_ERROR_SIZE
RM2M_REG_ERROR_INVALID
RM2M_REG_ERROR_ISNULL
= -202,
= -203,
= -204,
= -205,
= -206,
= -207,
= -208,
= -209,
// Not enough tokens were provided
// Invalid character inside JSON string
/* The string is not a full JSON packet, more
bytes expected */
// memory allocation failed
/* not enough token available for this
object/array size */
// found invalid pair (string : value)
// not enough tokens free for appending
// specified pair not found
// token type mismatch
// invalid parameters
// size exceeds maximum allowed
// JSON structure invalid
// value is null
Configuration flags for the rM2M_RegInit() function
RM2M_REG_VOLATILE
Rev. 01
= 0b00000001, // volatile storage (RAM)
117
12.3.8.2 Callback functions
public func(reg);
Function to be provided by the script developer, that is called up if the registration has changed
Parameter
reg
Explanation
Index of the registration memory block (see "Indices of the registration memory
blocks" in chapter "Constants" on page 117) that has been changed
12.3.8.3 Functions
native rM2M_RegInit(reg, flags, data{}, len=sizeof data);
initialises one of the optional registration memory blocks stored in the RAM. Calling up the function is
only necessary for the registration memory blocks listed in the explanation of the "reg" parameter.
Detailed information on the registration memory blocks is provided in chapter "Registration memory
blocks" on page 32.
Parameter
reg
Explanation
Registration memory block index
The following registration memory blocks require an initialisation:
l
flags
RM2M_REG_APP_STATE: Application-specific, volatile data (e.g.
current device status)
Configuration flags to be set/deleted
Bit0: Type of storage
0 = invalid, currently not supported
RM2M_REG_VOLATILE = saved in RAM in volatile manner
data
Array to store the registration memory block
len
Size (in cells) of the transferred array to store the registration memory block (max.
1kB ) - OPTIONAL
Explanation
Return value
OK, if successful
ERROR, if an unspecified errors occurs
l < OK, if another error occurs (see "Error codes for the registration memory
block access operations" in chapter "Constants" on page 117)
l
l
118
Rev. 01
Chapter 12 Device Logic (Pawn)
native rM2M_RegGetString(reg, const name[], string[], len=sizeof string);
Reads a character string from a registration memory block. Detailed information on the registration
memory blocks is provided in chapter "Registration memory blocks" on page 32.
Parameter
reg
Explanation
Index of the registration memory block (see "Indices of the registration memory
blocks" in chapter "Constants" on page 117)
name
Name of the entry
string
Array to store the string to be read
len
Size (in cells) of the transferred array to store the string to be read - OPTIONAL
Explanation
Return value
OK, if successful
ERROR, if an unspecified errors occurs
l RM2M_REG_ERROR_NOTFOUND, if the specified entry does not exist
l RM2M_REG_ERROR_ISNULL if the value of the specified entry is set to
"null"
l < OK, if another error occurs (see "Error codes for the registration memory
block access operations" in chapter "Constants" on page 117)
l
l
native rM2M_RegGetValue(reg, const name[], &{Float,Fixed,_}:value, tag=tagof value);
reads a value from a registration memory block. Detailed information on the registration memory blocks
is provided in chapter "Registration memory blocks" on page 32.
Parameter
reg
Explanation
Index of the registration memory block (see "Indices of the registration memory
blocks" in chapter "Constants" on page 117)
name
Name of the entry
value
Variable to store the value to be read
tag
The integer and floating-point conversion are differentiated by the "tag" of the
variables. - OPTIONAL
Explanation
Return value
OK, if successful
ERROR, if an unspecified errors occurs
l RM2M_REG_ERROR_NOTFOUND, if the specified entry does not exist
l RM2M_REG_ERROR_ISNULL if the value of the specified entry is set to
"null"
l < OK, if another error occurs (see "Error codes for the registration memory
block access operations" in chapter "Constants" on page 117)
l
l
Rev. 01
119
native rM2M_RegSetString(reg, const name[], const string[]);
Writes a character string into a registration memory block. Detailed information on the registration
memory blocks is provided in chapter "Registration memory blocks" on page 32.
Parameter
reg
Explanation
Index of the registration memory block (see "Indices of the registration memory
blocks" in chapter "Constants" on page 117)
name
Name of the entry
If an entry with this name already exists, the existing character string is replaced
by the transferred character string. Otherwise a new entry is created.
string
Array that contains the string to be written
Explanation
Return value
OK, if successful
ERROR, if an unspecified errors occurs
l < OK, if another error occurs (see "Error codes for the registration memory
block access operations" in chapter "Constants" on page 117)
l
l
native rM2M_RegSetValue(reg, const name[], {Float,Fixed,_}:value, tag=tagof value);
Writes a value into a registration memory block. Detailed information on the registration memory blocks
is provided in chapter "Registration memory blocks" on page 32.
Parameter
reg
Explanation
Index of the registration memory block (see "Indices of the registration memory
blocks" in chapter "Constants" on page 117)
name
Name of the entry
If an entry with this name already exists, the existing value is replaced by the
transferred value. Otherwise a new entry is created.
value
Value to be written
tag
The integer and floating-point conversion are differentiated by the "tag" of the
value. - OPTIONAL
Explanation
Return value
OK, if successful
ERROR, if an unspecified errors occurs
l < OK, if another error occurs (see "Error codes for the registration memory
block access operations" in chapter "Constants" on page 117)
l
l
120
Rev. 01
Chapter 12 Device Logic (Pawn)
native rM2M_RegDelValue(reg, const name[]);
Searches for an entry based on its name and sets the value of this entry (regardless of whether it is a
string or value) to "null". Detailed information on the registration memory blocks is provided in chapter
"Registration memory blocks" on page 32.
reg
Parameter
Explanation
Index of the registration memory block (see "Indices of the registration memory
blocks" in chapter "Constants" on page 117)
name
Name of the entry for which the value should be set to "null"
Explanation
Return value
OK, if successful
ERROR, if an unspecified errors occurs
l < OK, if another error occurs (see "Error codes for the registration memory
block access operations" in chapter "Constants" on page 117)
l
l
native rM2M_RegDelKey(reg, const name[]);
Searches for an entry based on its name and deletes the entry from the registration memory block.
Detailed information on the registration memory blocks is provided in chapter "Registration memory
blocks" on page 32.
reg
Parameter
Explanation
Index of the registration memory block (see "Indices of the registration memory
blocks" in chapter "Constants" on page 117)
name
Name of the entry that should be deleted from the registration memory block
Return value
Rev. 01
Explanation
OK, if successful
l ERROR, if an unspecified errors occurs
l < OK, if another error occurs (see "Error codes for the registration memory
block access operations" in chapter "Constants" on page 117)
l
121
native rM2M_RegOnChg(funcidx);
Specifies the function that should be called up if one of the registration memory blocks has changed.
Detailed information on the registration memory blocks is provided in chapter "Registration memory
blocks" on page 32.
Parameter
funcidx
Explanation
Index of the public function that should be called up if the registration has changed
Type of function: public func(reg);
Explanation
Return value
l
l
OK, if successful
< OK, if an error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84)
12.3.9 Position
12.3.9.1 Arrays with symbolic indices
TNMEA_GGA
Information (position, height above sea level and accuracy) extracted from a GGA data record
// Lat
//
//
//
//
// Long
//
//
// Alt
// Qual
// SatUsed
// HDOP
geographical latitude in degrees (resolution: 0.000001°)
-90,000,000 = South pole 90° S,
0 = Equator,
+90,000,000 = North pole 90° N
geographical longitude in degrees (resolution: 0.000001°)
-180,000,000 =180° West, 0 =Zero meridian, +180,000,000 =180° East
Height above sea level in meters
NMEA Quality indicator(see "Constants" on page 122)
Number of satellites used for the positioning
relative accuracy of the horizontal position [0,01]
#define TNMEA_GGA[.Lat, .Long, .Alt, .Qual, .SatUsed, .HDOP]
12.3.9.2 Constants
NMEA error codes
Error codes of the function rM2M_SetPosNMEA()
RM2M_NMEA_ERR_DATATYPE = -2, // Data type (e.g. $GGSA) not supported.
RM2M_NMEA_ERR_SENTENCE = -3, // Sentence invalid (e.g. checksum error)
RM2M_NMEA_ERR_LATITUDE = -4, // Geographical latitude invalid
RM2M_NMEA_ERR_LONGITUDE = -5, // Geographical longitude invalid
RM2M_NMEA_ERR_ALTITUDE = -6, // Altitude above sea level invalid
RM2M_NMEA_ERR_SAT_USED = -7, // Number of satellites used invalid.
RM2M_NMEA_ERR_QUAL
= -8, // GPS quality indication not supported.
122
Rev. 01
Chapter 12 Device Logic (Pawn)
NMEA quality indicator
RM2M_NMEA_FIX_NOK
= 0,
RM2M_NMEA_FIX_GPS
= 1,
RM2M_NMEA_FIX_DGPS
= 2,
RM2M_NMEA_FIX_PPS
= 3,
RM2M_NMEA_FIX_RTK
= 4,
RM2M_NMEA_FIX_FLOATRTK = 5,
RM2M_NMEA_FIX_EST
= 6,
RM2M_NMEA_FIX_MAN
RM2M_NMEA_FIX_SIM
= 7,
= 8,
// invalid/no fix
// Non-differential GPS fix
// Differential GPS fix
// Precise positioning service (PPS)
// Real time kinematic (RTK)
// Float real time kinematic
// Estimated fix (dead reckoning, coupled
// navigation)
// Manual input mode
// Simulation mode
List of supported GNSS device IDs
Designed to identify the source of the NMEA data record (in accordance with the "Talker ID" used with
the NMEA 0183 standard)
RM2M_NMEA_DEVICE_GP = 0x244750,
RM2M_NMEA_DEVICE_GL = 0x24474C,
RM2M_NMEA_DEVICE_GA = 0x244741,
RM2M_NMEA_DEVICE_GN = 0x24474E,
// $GP (GPS)
// $GL (GLONASS)
// $GA (GALILEO)
// $GN (GENERIC GNSS)
List of supported NMEA data records
RM2M_NMEA_RECORD_GGA = 0x474741, // GGA (global positioning system fix data)
Rev. 01
123
12.3.9.3 Functions
native rM2M_SetPos(Lat, Long, Elev, Qual, SatUsed);
Saves the GPS position information in the device. A historical record is not maintained. This means that
the current position information always overwrites the last known position. The information is
transmitted to the myDatanet server and can, for example, be read out via the API (see "API" on page
187).
Parameter
Lat
Explanation
geographical latitude in degrees (resolution: 0.000001°)
-90 000 000 = South pole 90° south
0 = Equator
+90 000 000 = North pole 90° north
Long
geographical longitude in degrees (resolution: 0.000001°)
-180 000 000 = 180° west
0 = Zero meridian (Greenwich)
+180 000 000 = 180° east
Elev
Height above sea level in meters (Valid range: -999...+9999)
Qual
Quality indicator (GPS quality indicator)
SatUsed
RM2M_NMEA_FIX_NOK:
invalid/no fix
RM2M_NMEA_FIX_GPS:
non-differential GPS fix
RM2M_NMEA_FIX_DGPS:
differential GPS fix
RM2M_NMEA_FIX_PPS:
Precise positioning service (PPS)
RM2M_NMEA_FIX_RTK:
Real time kinematic (RTK)
RM2M_NMEA_FIX_FLOATRTK:
Float real time kinematic
RM2M_NMEA_FIX_EST:
Estimated fix (dead reckoning, coupled
navigation)
RM2M_NMEA_FIX_MAN:
Manual input mode
RM2M_NMEA_FIX_SIM:
Simulation mode
Number of satellites used for the positioning (valid range: 0 ... 99)
Explanation
Return value
l
l
OK, if successful
ERROR
Note: The parameters are checked against the specified range limits. The
function returns "ERROR" if the limits are not adhered to.
124
Rev. 01
Chapter 12 Device Logic (Pawn)
native rM2M_DecodeNMEA(const sentence{}, data[], len=sizeof data);
Decodes a transferred NMEA data record
Parameter
sentence
Explanation
NMEA data record from a GPS receiver starting with the '$' character.
Important note: The strings must be terminated ('\0') immediately after
the checksum.
data
Buffer (cell array) to store the decoded data
[0] :
Contains the GNSS device ID (see "List of supported GNSS device
IDs" in chapter "Constants" on page 122)
[1] :
Contains the type of decoded NMEA data record (see "List of
supported NMEA data records" in chapter "Constants" on page
122)
[2] ... [n] :
Dependent on type of decoded NMEA data record
For a type "RM2M_NMEA_RECORD_GGA" data record, the
remaining structure is the same as the "TNMEA_GGA" structure.
[2]: .Lat
[3]: .Long
[4]: .Alt
[5]: .Qual
[6]: .SatUsed
[7]: .HDOP
len
Return value
Rev. 01
Size (in cells) of the buffer to record the decoded data – OPTIONAL
Explanation
l positive value, if successful (number of filled array elements, i.e. cells)
l negative value, if an error has occurred (see "NMEA error codes" in
chapter "Constants" on page 122)
125
native rM2M_SetPosNMEA(const Sentence{});
Takes the GPS position information from the transferred NMEA data record and saves it in the device.
A historical record is not maintained. This means that the current position information always overwrites
the last known position. The information is transmitted to the myDatanet server and can, for example,
be read out via the API (see "API" on page 187).
Parameter
Sentence
Explanation
NMEA data record from a GPS receiver starting with the '$' character. The
following data records are currently supported:
l
$GPGGA - location specification (fix information)
Important note: The strings must be terminated ('\0') immediately after
the checksum.
Explanation
Return value
l
l
126
OK, if successful
< OK, if an error occurs (see "NMEA error codes" in chapter "Constants"
on page 122)
Rev. 01
Chapter 12 Device Logic (Pawn)
native rM2M_GetPos(&Lat, &Long, &Elev, &Qual=0, &SatUsed=0);
Reads out the GPS position information saved to the device
Parameter
Lat
Explanation
Variable to store the geographical latitude in degrees
(resolution: 0.000001°)
-90 000 000 = South pole 90° south
0 = Equator
+90 000 000 = North pole 90° north
Long
Variable to store the geographical longitude in degrees
(resolution: 0.000001°)
-180 000 000 = 180° west
0 = Zero meridian (Greenwich)
+180 000 000 = 180° east
Elev
Variable to store the height above sea level in metres
(valid range: -999...+9999)
Qual
Variable to store the quality indicator (GPS quality indicator) – OPTIONAL
SatUsed
Return value
Rev. 01
RM2M_NMEA_FIX_NOK:
invalid/no fix
RM2M_NMEA_FIX_GPS:
non-differential GPS fix
RM2M_NMEA_FIX_DGPS:
differential GPS fix
RM2M_NMEA_FIX_PPS:
Precise positioning service (PPS)
RM2M_NMEA_FIX_RTK:
Real time kinematic (RTK)
RM2M_NMEA_FIX_FLOATRTK:
Float real time kinematic
RM2M_NMEA_FIX_EST:
Estimated fix (dead reckoning, coupled
navigation)
RM2M_NMEA_FIX_MAN:
Manual input mode
RM2M_NMEA_FIX_SIM:
Simulation mode
Variable to store the number of satellites used for positioning – OPTIONAL
Explanation
OK if valid GPS position information is stored in the device
l < OK, if an error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84)
l
127
12.3.10 Math
Helpful constants
Definition
M_E
Value
2.7182818284590452354
e
M_LOG2E
1.4426950408889634074
log2 e
M_LOG10E
0.43429448190325182765
log10 e
M_LN2
0.69314718055994530942
ln 2
M_LN10
2.30258509299404568402
ln 10
M_PI
3.14159265358979323846
π
M_PI_2
1.57079632679489661923
π/2
M_PI_4
0.78539816339744830962
π/4
M_1_PI
0.31830988618379067154
1/π
M_2_PI
0.63661977236758134308
2/π
M_2_SQRTPI
1.12837916709551257390
2/sqrt(π)
M_SQRT2
1.41421356237309504880
sqrt(2)
M_SQRT1_2
0.70710678118654752440
1/sqrt(2)
Description
native fround(Float:x);
Commercially rounds the transferred float
Parameter
Explanation
x
Float that should be rounded
Return value
Explanation
Commercially rounded integral value
native min(value1, value2);
Supplies the smaller of the two transferred values
Parameter
value1
Explanation
Two values of which the smaller one is to be determined
value2
Return value
128
Explanation
The smaller of the two transferred values
Rev. 01
Chapter 12 Device Logic (Pawn)
native max(value1, value2);
Supplies the larger of the two transferred values
Parameter
value1
Explanation
Two values of which the larger one is to be determined
value1
Return value
Explanation
The larger of the two transferred values
native clamp(value, min=cellmin, max=cellmax);
Checks whether the transferred value is between "min" and "max"
Parameter
value
Explanation
Value that is to be checked
min
Lower limit
max
Upper limit
Explanation
"value" if the value is between "min" and "max"
l "min" is the value is less than "min"
l "max", if the value is greater than "max"
Return value
l
native swapchars(c);
Swaps the order of the bytes
Parameter
c
Return value
Explanation
Value for which the bytes should be swapped over
Explanation
Value for which the bytes in parameter "c" are swapped over (the lowest byte
becomes the highest byte)
The mode of operation of the following functions corresponds to that of the standard ANSI-C implementation:
native Float:sin(Float:x);
Sine of x
native Float:cos(Float:x);
Cosine of x
native Float:tan(Float:x);
Tangent of x
Rev. 01
129
native Float:asin(Float:x);
Arcsine(x) in the range [-π/2, π/2], x element of [-1, 1]
native Float:acos(Float:x);
Arccosine(x) in the range [0, π], x element of [-1, 1]
native Float:atan(Float:x);
Arctangent(x) in the range [-π/2, π/2]
native Float:atan2(Float:y, Float:x);
Arctangent(y/x) in the range [-π, π]
native Float:sinh(Float:x);
Hyperbolic sine of x
native Float:cosh(Float:x);
Hyperbolic cosine of x
native Float:tanh(Float:x);
Hyperbolic tangent of x
native Float:exp(Float:x);
Exponential function ex
native Float:log(Float:x);
Natural logarithm ln(x), x > 0
native Float:log10(Float:x);
Logarithm as the basis 10 log10(x), x > 0
native Float:pow(Float:x, Float:y);
xy. An argument error has occurred if x = 0 and y <= 0, or if x < 0 and y is not a whole number.
native Float:sqrt(Float:x);
Root x, x >= 0
native Float:ceil(Float:x);
Smallest whole number that is not smaller than x
native Float:floor(Float:x);
Largest whole number that is not larger than x
native Float:fabs(Float:x);
Absolute value | x |
native Float:ldexp(Float:x, n);
x*2n
native Float:frexp(Float:x, &n);
Breaks down x into a normalised mantissa in the range [1/2, 1] that is supplied as the result, and a
potency of 2 that is filed in n. If x is zero, both parts of the result are zero.
native Float:modf(Float:x, &Float:ip);
Breaks down x into an integral and residual part that both have the same prefix as x. The integral part is
filed in ip, while the residual part is the result.
native Float:fmod(Float:x, Float:y);
Residual floating point of x/y with the same prefix as x. The result is dependent on the implementation, if
y is zero.
native isnan(Float:x);
Returns a value that is not equal to zero, if x is not a number
130
Rev. 01
Chapter 12 Device Logic (Pawn)
12.3.11 Char & String
Note: You require the following include file to be able to use the functions in this chapter: #include
<string>
The mode of operation of the following functions essentially corresponds to that of the standard ANSI-C
implementation:
native strlen(const string[]);
Supplies the length of the string (without '\0')
Parameter
string
Explanation
Character string for which the length has to be determined
Return value
Explanation
Number of characters without the final '\0'
native sprintf(dest[], maxlength=sizeof dest, const format[], {Float,Fixed,_}:...);
Saves the transferred format string in the array dest. The mode of operation of the functions
corresponds to that of the "snprintf" function of the standard ANSI-C implementation.
Parameter
dest
Explanation
Array to store the formatted result
maxlength
Maximum number of characters that the array dest can store
format
The format character string to be used
Explanation
Return value
l
l
-1 in the event of a fault
Number of characters that would have been written if the array dest had
been long enough (without '\0').
The array dest is always assigned a final zero. The length of the array dest
cannot be exceeded.
native strcpy(dest[], const source[], maxlength=sizeof dest);
Copies the source character string to the array dest (including '\0').
Parameter
dest
Explanation
Array to store the character string that should be copied
source
Character string that should be copied
maxlength
Size (in Cells) of the array to store the string to be copied - OPTIONAL
Explanation
Return value
Rev. 01
Number of copied characters
131
native strcat(dest[], const source[], maxlength=sizeof dest);
Adds the source character string to the dest character string (including '\0')
Parameter
dest
Explanation
Array to store the result. This array already comprises one character string to
which the source character string should be added.
source
Character string that should be added to the character string included in the array
dest
maxlength
Size (in Cells) of the array to store the result - OPTIONAL
Explanation
Return value
Number of added characters
native strcmp(const string1[], const string2[], length=cellmax);
Compares character string1 and string2
Parameter
string1
Explanation
The two character strings that are to be compared
string2
length
The maximum number of characters that should be taken into consideration
during the comparison - OPTIONAL
Explanation
Return value
1: string1 > string 2
0: both of the character strings are the same (at least the length that is
taken into account)
l -1: string1 < string 2
l
l
native strchr(const string[], char);
Searches for a character (first occurrence) in a character string
Parameter
string
Explanation
Character string that should be searched
char
Character that the search is looking for
Return value
132
Explanation
l -1, if the character that the search is looking for is not included in the
character string
l Array index for the character that the search is looking for (first character
occurring in the character string)
Rev. 01
Chapter 12 Device Logic (Pawn)
native strrchr(const string[], char);
Searches for a character (last occurrence) in a character string
Parameter
string
Explanation
Character string that should be searched
char
Character that the search is looking for
Return value
Explanation
l -1, if the character that the search is looking for is not included in the
character string
l Array index for the character that the search is looking for (last character
occurring in the character string)
native strspn(const string1[], const string2[]);
Searches for the position of the first character in string1 that is notincluded in the character string of
permitted characters (string2)
Parameter
string1
Explanation
Character string that should be searched
string2
Character string of permitted characters
Return value
Explanation
l Length of string1 if no permitted characters are found
l
Position of the first character in the character string that should be
searched that is not included in the character string of permitted characters
native strcspn(const string1[], const string2[]);
Searches for the position of the first character in string1 that is also included in the character string of
permitted characters (string2)
Parameter
string1
Explanation
Character string that should be searched
string2
Character string of permitted characters
Return value
Rev. 01
Explanation
l Length of string1 if no permitted character has been found
l Position of the first character in the character string that should be
searched that is also included in the character string of permitted
characters
133
native strpbrk(const string1[], const string2[]);
Searches the array index of the first character that is also included in the character string of permitted
characters
Parameter
string1
Explanation
Character string that should be searched
string2
Character string of permitted characters
Return value
Explanation
l -1, if the character that the search is looking for is not included in the
character string
l Array index of the first character in the character string that should be
searched that is also included in the character string of permitted
characters
native strstr(const string1[], const string2[]);
Searches character string2 in character string1
Parameter
string1
Explanation
Character string that should be searched
string2
Character string that the search should be for
Return value
Explanation
-1, if character string2 that is being searched for is not included in string1
l Array index where character string2 that is being searched for starts in
string1
l
native strtol(const string[], base);
Converts a character string into a value
Parameter
string
Explanation
Character string that is to be converted
base
Specifies the basis that must be used for the conversion
2-36: The specified basis is used
0: 8, 10 or 16 is used as the basis, depending on the
character string that must be converted
Basis 8: with a leading 0
Basis 16: with 0x or 0X
Return value
134
Explanation
Value that corresponds to the character string
Rev. 01
Chapter 12 Device Logic (Pawn)
native Float: atof(const string[]);
Converts a character string into a float
Parameter
string
Explanation
Character string that is to be converted
Return value
Explanation
Float for which the numerical value corresponds to the character string
native tolower(c);
Converts a character into lower case
Parameter
c
Return value
Explanation
Character that should be converted to lower case
Explanation
The lower case variant of the transferred character, if available, or the unchanged
character code of "c" if the letter "c" does not have a lower case equivalent.
native toupper(c);
Converts a character into upper case
Parameter
c
Return value
Rev. 01
Explanation
Character that should be converted to upper case
Explanation
The upper case variant of the transferred character, if available, or the
unchanged character code of "c" if the letter "c" does not have a upper case
equivalent.
135
12.3.12 CRC & hash
12.3.12.1 Arrays with symbolic indices
TMD5_Ctx
Context structure for the MD5 calculation
// init
//
//
//
// tmp
After being set to "0", the context structure can be used to
calculate a new hash. If a calculation
should be implemented by calling up the "MD5" function repeatedly,
write access must not be granted for this element.
no write access permitted for internal use
#define TMD5_Ctx[.init, .tmp[22]]
12.3.12.2 Functions
native CRC16(data{}, len, initial=0xFFFF);
Returns the calculated modbus CRC16 of the transferred data
Parameter
data
Explanation
Array that contains the data for which the CRC16 should be calculated
len
Number of bytes that must be taken into consideration during the calculation
initial
Initial value for calculating the CRC16 - OPTIONAL
Return value
Calculated CRC16
Explanation
native CRC32(data{}, len, initial=0);
Returns the calculated Ethernet CRC32 of the transferred data
Parameter
data
Explanation
Array that contains the data for which the CRC32 should be calculated
len
Number of bytes that must be taken into consideration during the calculation
initial
Initial value for calculating the CRC32 - OPTIONAL
Explanation
Return value
136
Calculated CRC32
Rev. 01
Chapter 12 Device Logic (Pawn)
native MD5(data{}, len, hash{16}, ctx[TMD5_Ctx] = [0]);
Calculates the MD5 hash for the transferred data. If the hash for a data block should be calculated by
calling up this function several times (e.g. when receiving data in blocks), then the same context
structure must be transferred every time the function is called up. The context structure must not be
changed between function call-ups. If the hash can be calculated by calling up the function once (e.g.
complete data block is already available), then it is not necessary to transfer its own context structure.
Parameter
data
Explanation
Array that contains the data for which the MD5 hash should be calculated
len
Number of bytes that must be taken into consideration during the calculation
hash
Array to store the calculated 128-bit hash value
ctx
Context structure for the MD5 calculation – OPTIONAL
Return value
---
Explanation
12.3.13 Various
12.3.13.1 Arrays with symbolic indices
TablePoint
Two-column reference point table, integer data type
// key
// value
Column that is searched
Column with the result values that need to be returned
#define TablePoint[.key, .value]
TablePointF
Two-column reference point table, float data type
// key
// value
Column that is searched
Column with the result values that need to be returned
#define TablePointF[Float:.key, Float:.value]
Rev. 01
137
TrM2M_Id
Information for identifying the module/device
// string
// module
// hwmajor
// hwminor
// sn
//
// fwmajor
// fwminor
// ctx
//
rapidM2M module identification (e.g. "rapidM2M EasyIoT
HW1.1")
rapidM2M module type (e.g. "EasyIoT")
Hardware: Major version number
Hardware: Minor version number
Device serial number (binary) in BIG endian format
E.g.: "010146AF251CED1C" --> "01" in sn{0}, "1C" in sn{7}
Firmware: Major version number
Firmware: Minor version number
Site title (context)
Empty string if no context available
#define TrM2M_Id[
.string{50}, .module{10}, .hwmajor, .hwminor,
.sn{8}, .fwmajor, .fwminor, .ctx{50}
]
TRTM_Data
Information regarding the runtime measurement
// runtime
// instructions
// tmp
Determined runtime in [ms]
Number of executed pawn instructions
For internal use, no write access permitted
#define TRTM_Data[.runtime, .instructions, .tmp[3]]
12.3.13.2 Constants
Error codes for the "CalcTable" and "CalcTableF" functions
const
{
TAB_ERR_FLOOR = -1, // searched value lower than the first table entry
TAB_ERR_CEIL = -2, // searched value higher than the last table entry
};
12.3.13.3 Functions
native getapilevel();
Issues the implemented API level of the script engine
Return value
138
Explanation
Implemented API level of the script engine
Rev. 01
Chapter 12 Device Logic (Pawn)
native exists(const name[]);
checks whether the required rapidM2M API function is supported by the device firmware
Parameter
name
Return value
Explanation
Name of the required rapidM2M API function
Explanation
l true, if the function is available
l false, if the device firmware does not support the function
native loadmodule(mod{});
Loads a script module at the runtime. This enables the pawn engine to be extended by its own native
functions. The implementation of operations as a native function means that processing speeds can be
increased significantly in comparison to the implementation in pawn. A script module can contain
several native functions. After calling up this function, the native functions contained in the script module
can be used in the same way as the standard functions available in the pawn engine.
Parameter
mod
Explanation
Byte array that contains the script module to be loaded.
Explanation
Return value
l
l
OK, if successful
ERROR, if an error occurs
native rtm_start(measurement[TRTM_Data]);
Starts a runtime measurement
Parameter
measurement
Explanation
Structure for recording the information regarding a runtime measurement
Important note: This structure must be persistent from calling up "rtm_
start()" to calling up "rtm_stop()".
Explanation
Return value
l
l
Rev. 01
OK, if successful
ERROR, if an error occurs
139
native rtm_stop(measurement[TRTM_Data]);
Stops the runtime measurement and calculates the time in [ms] since the "rtm_start()" function was
called up and the pawn instructions executed since then. The determined values are written in the
".runtime" and ".instructions" elements of the transferred structure to record the information regarding a
runtime measurement.
Parameter
measurement
Explanation
Structure for recording the information regarding a runtime measurement
Important note: This structure must be persistent from calling up "rtm_
start()" to calling up "rtm_stop()".
Explanation
Return value
l
l
140
OK, if successful
ERROR, if an error occurs
Rev. 01
Chapter 12 Device Logic (Pawn)
native CalcTable(key, &value, const table[][TablePoint], size = sizeof table);
Searches for a certain value in the "key" column of the transferred reference point table and supplies
the relevant value from the "value" column in the table. If the searched value is between two reference
points, the returned value is interpolated linearly between the two adjacent values in the "value" column
(linear equation: y = k*x + d). Non-linear characteristic curves (e.g. connection between ADC value ->
temperature) can be reproduced with this function.
Parameter
Explanation
key
Value that is used for the search
value
Includes the result of the calculation by the function
table
The table that is searched must be a "TablePoint" type table.
size
Number of rows in the table
Return value
Explanation
OK, if the relevant value was found
l TAB_ERR_FLOOR, if the searched value is lower than the first table entry.
"value" contains the first table entry.
l TAB_ERR_CEIL, if the searched value is higher than the last table entry.
"value" contains the last table entry.
l < OK, if another error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84).
l
Note: Additional explanation on the "table" reference point table
The rows of the table can be displayed in an x/y coordinate system. The values in the "key" column are
displayed on the X axis and the associated values in the "value" column are displayed on the Y axis.
Display of the reference point table as an x/y coordinate system
native CalcTableF(Float:key, &Float:value, const table[][TablePointF], size = sizeof table);
The functionality is the same as that of the "CalcTable" function. The difference is that "Float" is the data
type for all elements of the "CalcTableF" function.
Rev. 01
141
native rM2M_GetId(id[TrM2M_Id], len=sizeof id);
Provides the information to identify the module/device
Parameter
id
Explanation
Structure for storing the information to identify the module/device (see "TrM2M_
Id" in chapter "Arrays with symbolic indices" on page 137)
len
Size (in cells) of the structure to store the information - OPTIONAL
Return value
Explanation
l Size (in cells) of the structure used to store the information
l ERROR if the address and/or length of the ID structure are invalid (outside
the script data memory)
l < OK, if another error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84).
Note: The firmware of a module/device detects if a script is being used for which
the function only has one transfer parameter (older include file is being used) and
for compatibility reasons therefore returns "OK" instead of the size of the
structure for storing the information.
native heapspace();
Supplies the free memory capacity to the heap
Return value
Explanation
The free memory capacity to the heap. The stack and the heap have a joint
memory area, so that this value specifies the number of bytes that remain for the
stack or the heap.
native funcidx(const name[]);
Supplies the index of a public function
Parameter
name
Return value
Explanation
Name of the public function
Explanation
l -1, if there is no function with the transferred name
l Index of the public function
native numargs();
Returns the number of arguments transferred to a function
Return value
142
Explanation
The number of arguments that have been transferred to a function. numargs is
useful within functions with a variable list of arguments.
Rev. 01
Chapter 12 Device Logic (Pawn)
native getarg(arg, index=0);
Supplies the value of the argument
Parameter
arg
Explanation
The sequence number of the argument. Use 0 for the first argument.
index
Index if "arg" refers to an array
Return value
Explanation
This function supplies an argument from a variable argument list. If the argument
is an array, the "index" specifies the index of the required array element. The
return value is the value of the argument.
native setarg(arg, index=0, value);
Sets the value of the argument
arg
Parameter
Explanation
The sequence number of the argument. Use 0 for the first argument.
index
Index if "arg" refers to an array
value
Value to which the argument should be set
Return value
Explanation
l true, if the value could be set
l false, if the argument or index are invalid
This function sets an argument in a variable argument list. If the argument is an
array, the "index" specifies the index of the required array element.
native rand();
Returns a random number from the "32-Bit signed Integer" value range. However, value "-1" (ERROR)
is reserved for returning an error.
Return value
Rev. 01
Explanation
Random number from the "32-Bit signed Integer" value range
l ERROR if no random number generator is available
l
143
12.3.14 Console
native print(const string[]);
Prints the specified string to the standard output
Parameter
string
Explanation
The character string to be issued. This can include escape sequences.
Return value
OK
Explanation
native printf(const format[], {Float,Fixed,_}:...);
Prints the transferred format string to the standard output. The mode of operation of the functions
corresponds to that of the standard ANSI-C implementation.
Parameter
format[]
Return value
Explanation
The format character string to be used
Explanation
l Number of printed characters
l ERROR, if not successful
native setbuf(buf{}, size);
Provides the firmware with a buffer from the RAM area reserved for the script that is used to output
strings via the "printf()" function. When this function is called up, the system switches from the 256 byte
buffer integrated in the firmware to the transferred buffer.
Parameter
buf
Explanation
Static byte array that should be used as a buffer to output strings
size
Size of the buffer in bytes
Note: If the function is called up again and the size is set to "0" during the
process, then the system switches back to the integrated buffer (256 bytes). The
transferred static byte array can then be used by the script again.
Explanation
Return value
l
l
144
OK, if successful
ERROR, if not successful
Rev. 01
Chapter 12 Device Logic (Pawn)
12.3.15 Universal inputs
Note: You require the following include file to be able to use the functions in this chapter: #include
<ui>
12.3.15.1 Constants
Selection of the mode for an universal input
Input modes for the UI_Init() function
UI_CHT_SI_NONE
= 0,
UI_CHT_SI_DIGITAL = 1,
UI_CHT_SI_DCTR
= 2,
UI_CHT_SI_DFREQ
= 3,
UI_CHT_SI_DPWM
= 4,
UI_CHT_SI_A020MA = 5,
UI_CHT_SI_A002V
= 6,
UI_CHT_SI_A010V
= 7,
UI_CHT_SI_DIRECT = 8,
// Deactivated
// Digital
// Counter
// Frequency
// PWM
// 0/4...20mA
// 0...2V
// 0...10V
// Direct (corresponds to
// 0...2V mode on the myDatalogEASY IoTmini )
Sample rate in [Hz] for the measurement
UI_SAMPLE_RATE_2
=
2,
UI_SAMPLE_RATE_4
=
4,
UI_SAMPLE_RATE_8
=
8,
UI_SAMPLE_RATE_16 = 16,
UI_SAMPLE_RATE_32 = 32,
UI_SAMPLE_RATE_64 = 64,
UI_SAMPLE_RATE_128 = 128,
Rev. 01
145
12.3.15.2 Functions
native UI_Init(channel, mode, filtertime);
Initialises an universal input (UI 1 - UI 4 ). The sample rate for acquiring the measurement value is
configured by the "UI_SetSampleRate" function. Calling up the "UI_SetSampleRate" function is only
necessary, if the default sample rate setting of 16Hz (62,5ms) is not suitable for your application.
Detailed information on the universal inputs is provided in chapter "Technical details about the universal
inputs" on page 55.
Note: The energy consumption increases with each universal input that is initialised.
Parameter
channel
Explanation
Number of the universal input, starting with 0 for UI 1
Note: You can also use the predefined constants for this parameter (see
"Numbers of the universal inputs" in the chapter "System" on page 95).
mode
Selection of the mode for the universal input
UI_CHT_SI_NONE :
Universal input deactivated
UI_CHT_SI_DIGITAL Digital: max. 32V, low <0,99V, high >2,31V, load
:
10k086
UI_CHT_SI_DCTR :
Counter: min. pulse length 1ms, load 10k086
UI_CHT_SI_DFREQ : Frequency: 1...1000Hz, 10k086
UI_CHT_SI_DPWM : PWM: 1...99%, max. 100Hz, min. pulse length 1ms,
load 10k086
UI_CHT_SI_A020MA 0/4...20mA: Resolution 6,3µA, max. 23,96mA, load 96Ω
:
UI_CHT_SI_A002V :
0...2V: Resolution 610µV, max. 2,5V, load 10k086
UI_CHT_SI_A010V :
0...10V: Resolution 7,97mV, max. 32V, load 4k7
UI_CHT_SI_DIRECT Direct (corresponds to 0...2V mode on the
:
myDatalogEASY IoTmini )
filtertime
"Digital", "Counter", "Frequency" and "PWM" modes:
Time in [ms] during which the signal must remain constant to initiate a level
change. Used to suppress brief faults (debouncing).
"0/4...20mA", "0...2V", "0...10V" and "direct" modes:
Time in [ms] during which the analogue signal is averaged for signal smoothing.
Used to suppress signal noise.
Explanation
Return value
OK, if successful
ERROR_NOT_SUPPORTED, if the selected mode is not supported by
this universal input
l < OK, if another error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84).
l
l
146
Rev. 01
Chapter 12 Device Logic (Pawn)
native UI_Close(channel);
Deactivates an universal input (UI 1 - UI 4 ). Detailed information on the universal inputs is provided in
chapter "Technical details about the universal inputs" on page 55.
Note: The energy consumption decreases with each universal input that is deactivated.
Parameter
channel
Explanation
Number of the universal input, starting with 0 for UI 1
Note: You can also use the predefined constants for this parameter (see
"Numbers of the universal inputs" in the chapter "System" on page 95).
Explanation
Return value
l
l
OK, if successful
ERROR, if an invalid parameter was transferred
native UI_GetValue(channel, &value=0);
Reads the last valid measurement value for the specified universal input from the system. Detailed
information on the universal inputs is provided in chapter "Technical details about the universal inputs"
on page 55.
Parameter
temp
Explanation
Number of the universal input, starting with 0 for UI 1
Note: You can also use the predefined constants for this parameter (see
"Numbers of the universal inputs" in the chapter "System" on page 95).
value
Variable to store the measurement value to be read out. The way in which the
measurement value has to be interpreted, is dependent on the universal input
mode.
UI_CHT_SI_NONE :
---
UI_CHT_SI_DIGITAL Digital: 0 =^ "low", 1 =^ "high"
:
UI_CHT_SI_DCTR :
Counter reading []
UI_CHT_SI_DFREQ : Frequency in [Hz]
UI_CHT_SI_DPWM : PWM in [%]
UI_CHT_SI_A020MA 0/4...20mA: Current in [µA]
:
UI_CHT_SI_A002V :
0...2V: Voltage in [mV]
UI_CHT_SI_A010V :
0...10V: Voltage in [mV]
UI_CHT_SI_DIRECT direct: Voltage in [mV]
:
Explanation
Return value
l
l
Rev. 01
OK, if successful
ERROR, if an invalid parameter was transferred
147
native UI_SetSampleRate(samplerate);
Sets the sample rate for the measurement value acquisition at the universal inputs. The specified
setting is always valid for all of the universal inputs. Special settings for individual universal inputs are
not possible. The default value of the sample rate is 16Hz (62,5ms) . Detailed information on the
universal inputs is provided in chapter "Technical details about the universal inputs" on page 55.
Note: The energy consumption increases when the sample rate is increased.
Note: The selected option also influences the possible value range for the pulse duration of the
isolated switch contact in "pulse/min." mode.
Parameter
samplerate
Explanation
Sample rate in [Hz]
Note: Only the constants specified in "Sample rate in [Hz] for the
measurement" in chapter "Constants" on page 145are permissible for this
parameter.
Return value
Explanation
OK, if successful
l ERROR, if an invalid parameter was transferred
l
Note: The sample rate for the universal inputs operated in "Counter", "Frequency" or "PWM" modes is
not relevant. You can use the lowest possible value for the sample rate, if you operate all of the universal
inputs in these modes and do not operate the isolated switch contact in "pulse/min." mode.
native UI_ResetCounter(channel);
Resets the counter reading of an universal input that is being operated in "Counter" mode. If no error
occurred during this process, the function returns the counter reading value before resetting the
counter. Detailed information on the universal inputs is provided in chapter "Technical details about the
universal inputs" on page 55.
Parameter
channel
Explanation
Number of the universal input, starting with 0 for UI 1
Note: You can also use the predefined constants for this parameter (see
"Numbers of the universal inputs" in the chapter "System" on page 95).
Return value
148
Explanation
l Counter reading before the reset
l ERROR, if an invalid parameter was transferred
Rev. 01
Chapter 12 Device Logic (Pawn)
12.3.16 Outputs
12.3.16.1 Constants
Numbers of the digital outputs
DIGOUT_CHANNEL1
= 0,
// isolated switch contact 1
//Number of digital outputs, with which the myDatalogEASY IoTmini is equipped
DIGOUT_NUM_CHANNELS = 1,
Selection of the output voltage for the switchable sensor supply VOUT
Configuration options for the Vsens_On() function
VSENS_15V = 0,
// 14,7V at Iout = 50mA
VSENS_24V = 1,
// 23,4V at Iout = 50mA
Selection of the mode for the isolated switch contact (NO, CC)
Output modes for the DigOut_Init() function
DIGOUT_OFF
= 0,
DIGOUT_DIG
= 1,
DIGOUT_FREQ
= 2,
DIGOUT_PWM
= 3,
DIGOUT_IMPULSE_PER_MINUTE = 4,
DIGOUT_IMPULSE_ONCE
= 5,
// deactivated
// digital output
// frequency output
// PWM output
// pulse/min.
// single output of x pulses
12.3.16.2 Functions
native Vsens_On(mode);
Activates the switchable sensor supply VOUT. The output voltage (14,7V or 23,4V ) can be selected
via the "Mode" parameter. Detailed information on the switchable sensor supply is provided in chapter
"Switchable sensor supply VOUT" on page 59.
Parameter
mode
Explanation
Selection of the output voltage VOUT
VSENS_15V: 14,7V at Iout = 50mA
VSENS_24V: 23,4V at Iout = 50mA
Explanation
Return value
l
l
Rev. 01
OK, if successful
< OK, if an error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84)
149
native Vsens_Off();
Deactivates the switchable sensor supply VOUT. Detailed information on the switchable sensor supply
is provided in chapter "Switchable sensor supply VOUT" on page 59.
Explanation
Return value
l
l
OK, if successful
< OK, if an error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84)
native Ext3V3_On();
Activates the switchable 3,3V supply voltage VEXT. Detailed information on the switchable 3,3V supply
voltage is provided in chapter "Switchable sensor supply VEXT" on page 60.
Explanation
Return value
l
l
OK, if successful
< OK, if an error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84)
native Ext3V3_Off();
Deactivates the switchable 3,3V supply voltage VEXT. Detailed information on the switchable 3,3V
supply voltage is provided in chapter "Switchable sensor supply VEXT" on page 60.
Return value
150
Explanation
OK, if successful
l < OK, if an error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84)
l
Rev. 01
Chapter 12 Device Logic (Pawn)
native DigOut_Init(digout, mode, cfg1 = -1, cfg2 = -1);
Initialises the isolated switch contact (NO, CC). The mode is selected via the "mode" parameter. The
meaning of the "cfg1" and "cfg2" parameters is dependent on the selected mode. Detailed information
on the isolated switch contact is provided in chapter "Isolated switch contact (NO, CC)" on page 61.
Note: Using "DIGOUT_FREQ" (Frequency output) and "DIGOUT_PWM" (PWM output)
modes drastically increases the energy consumption.
Parameter
digout
Explanation
Number of the digital output (isolated switch contact); is always 0 for the
myDatalogEASY IoTmini
mode
Selection of the mode for the isolated switch contact (NO, CC)
cfg1
cfg2
DIGOUT_OFF :
Isolated switch contact deactivated
DIGOUT_DIG :
Digital output
DIGOUT_FREQ :
Frequency output
DIGOUT_PWM :
PWM output
DIGOUT_IMPULSE_PER_
MINUTE:
Pulse/min.
DIGOUT_IMPULSE_ONCE:
Single output of x pulses
DIGOUT_OFF :
Not used
DIGOUT_DIG :
Not used
DIGOUT_FREQ :
Pulse duty factor: 1...100% (default: 50%)
DIGOUT_PWM :
Frequency: 0...1000Hz (default: 100Hz)
DIGOUT_IMPULSE_PER_
MINUTE:
Pulse duration: Dependent on the sample
rate of the universal inputs1) (default:
100ms)
DIGOUT_IMPULSE_ONCE:
Pulse duration: 1...500ms (default: 100ms)
DIGOUT_OFF :
Not used
DIGOUT_DIG :
Not used
DIGOUT_FREQ :
Not used
DIGOUT_PWM :
Not used
DIGOUT_IMPULSE_PER_
MINUTE:
Not used
DIGOUT_IMPULSE_ONCE:
Pulse pause: 1...500ms (default: 100ms)
1)Only a multiple of the sample rate for the universal inputs selected via the "UI_SetSampleRate()"function can be
set for the pulse duration in "Pulse/min." mode. The actual pulse duration is calculated as follows:
Pulse duration = (cfg1/sample rateUI + 1) x sample rateUI
Rev. 01
151
Explanation
Return value
l
l
OK, if successful
< OK, if an error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84)
native DigOut_Close(digout);
Deactivates the isolated switch contact (NO, CC). Detailed information on the isolated switch contact is
provided in chapter "Isolated switch contact (NO, CC)" on page 61.
Parameter
digout
Explanation
Number of the digital output (isolated switch contact); is always 0 for the
myDatalogEASY IoTmini
Explanation
Return value
l
l
152
OK, if successful
< OK, if an error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84)
Rev. 01
Chapter 12 Device Logic (Pawn)
native DigOut_SetValue(digout, value);
Specifies the setpoint for the isolated switch contact (NO, CC). The meaning of the "value" parameter is
dependent on the mode of the isolated switch contact selected via the "DigOut_Init" function. Detailed
information on the isolated switch contact is provided in chapter "Isolated switch contact (NO, CC)" on
page 61.
Parameter
digout
Explanation
Number of the digital output (isolated switch contact); is always 0 for the
myDatalogEASY IoTmini
value
DIGOUT_OFF :
---
DIGOUT_DIG :
=0: "low" (contact open)
> 1: "high" (contact closed)
DIGOUT_FREQ :
Frequency 1...1000Hz
DIGOUT_PWM :
PWM 0...100%
DIGOUT_IMPULSE_PER_
MINUTE:
Number of pulses that should be issued per
minute
DIGOUT_IMPULSE_ONCE:
Number of pulses that should be issued
Explanation
Return value
l
l
OK, if successful
< OK, if an error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84)
Note:
Additional explanation on "Pulse/min." mode (DIGOUT_IMPULSE_PER_MINUTE):
Note that the maximum number of pulses that can be issued per minute is dependent on the pulse
duration specified via the "DigOut_Init" function:
Pulse duration = (cfg1/sample rateUI + 1) x sample rateUI
Number of pulsesmax = 60,000 ms / (pulse duration + sample rateUI)
Note:
Additional explanation on "Pulse" mode (DIGOUT_IMPULSE_ONCE):
The time required to issue the specified number of pulses is dependent on the pulse duration and pulse
pause specified via the "DigOut_Init" function:
t = number of pulses x (pulse duration + pulse pause)
Rev. 01
153
native RS232_3V3_On();
Activates the switchable 3,3V supply voltage VEXTRS232. Detailed information on the switchable 3,3V
supply voltage VEXTRS232 is provided in chapter "Switchable sensor supply VEXTRS232" on page 61.
Explanation
Return value
l
l
OK, if successful
< OK, if an error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84)
native RS232_3V3_Off();
Deactivates the switchable 3,3V supply voltage VEXTRS232. Detailed information on the switchable
3,3V supply voltage VEXTRS232 is provided in chapter "Switchable sensor supply VEXTRS232" on
page 61.
Explanation
Return value
l
l
OK, if successful
< OK, if an error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84)
12.3.17 LED
Note: You require the following include file to be able to use the functions in this chapter: #include
<led>
12.3.17.1 Constants
Selection of whether the two-colour LED is controlled by the firmware or script
Configuration options for the Led_Init() function
LED_MODE_INTERNAL = 0,
LED_MODE_SCRIPT
= 1,
154
// controlled by the FW
// controlled by the script
Rev. 01
Chapter 12 Device Logic (Pawn)
12.3.17.2 Functions
native Led_Init(mode);
Initialises the two-colour LED
Parameter
mode
Explanation
Selection of whether the two-colour LED is controlled by the firmware or script
LED_MODE_
INTERNAL :
The two-colour LED is used to indicate the operating
state (see "Two-colour LED" on page 71).
LED_MODE_SCRIPT : The state of the two-colour LED can be controlled by
the "Led_On", "Led_Off", "Led_Blink" and "Led_Flash"
script functions.
Explanation
Return value
l
l
OK, if successful
ERROR, if an invalid parameter was transferred
native Led_Close();
Deactivates the two-colour LED. The two-colour LED cannot be controlled by the firmware or the script
functions.
Explanation
Return value
OK, if successful
native Led_On(bool:red, bool:green);
The two-colour LED consists of a red and a green LED that can be switched on separately by this
function. If both LEDs are switched on simultaneously, the two-colour LED lights up orange.
Parameter
Explanation
red
true: The red LED is switched on.
green
true: The green LED is switched on.
Explanation
Return value
l
l
Rev. 01
OK, if successful
ERROR, if an invalid parameter was transferred
155
native Led_Off(bool:red, bool:green);
The two-colour LED consists of a red and a green LED that can be switched off separately by this
function.
Parameter
Explanation
red
true: The red LED is switched off.
green
true: The green LED is switched off.
Explanation
Return value
l
l
OK, if successful
ERROR, if an invalid parameter was transferred
native Led_Blink(red, green);
Enables the two-colour LED to flash (ton = 500ms , toff = 500ms ). The two-colour LED consists of a red
and a green LED. If both LEDs are used, the two-colour LED flashes orange.
Parameter
red
green
Explanation
-1 : The red LED remains switched off.
0 : The red LED flashes until it is deliberately switched off.
>0 : Number of times the red LED should flash
-1 : The green LED remains switched off.
0 : The green LED flashes until it is deliberately switched off.
>0 : Number of times the green LED should flash
Explanation
Return value
l
l
OK, if successful
ERROR, if an invalid parameter was transferred
native Led_Flash(red, green);
Enables the two-colour LED to briefly flash every 500ms . The two-colour LED consists of a red and a
green LED. If both LEDs are used, the two-colour LED briefly flashes orange.
Parameter
red
Explanation
-1 : The red LED remains switched off.
0 : The red LED briefly flashes at regular intervals until it is deliberately switched off
>0 : Number of times the red LED should briefly flash at regular intervals
green
-1 : The green LED remains switched off.
0 : The green LED briefly flashes at regular intervals until it is deliberately switched off
>0 : Number of times the green LED should briefly flash at regular intervals
Explanation
Return value
l
l
156
OK, if successful
ERROR, if an invalid parameter was transferred
Rev. 01
Chapter 12 Device Logic (Pawn)
native Led_Flicker(red, green);
Enables the two-colour LED to flicker (ton = 94ms , toff = 31ms ). The two-colour LED consists of a red
and a green LED. If both LEDs are used, the two-colour LED flickers orange.
Parameter
red
green
Return value
Explanation
-1 : The red LED remains switched off.
0 : The red LED flickers until it is deliberately switched off.
>0 : Number of times the red LED should flicker
-1 : The green LED remains switched off.
0 : The green LED flickers until it is deliberately switched off.
>0 : Number of times the green LED should flicker
Explanation
OK, if successful
l ERROR, if an invalid parameter was transferred
l
12.3.18 Solenoid switch
12.3.18.1 Constants
Selection of whether the solenoid switch is evaluated by the firmware or script
Configuration options for the Switch_Init() function
SWITCH_MODE_INTERNAL = 0,
SWITCH_MODE_SCRIPT
= 1,
// evaluation by the FW
// evaluation by the script
12.3.18.2 Callback Funktionen
public func(key);
Function to be provided by the script developer, that is called when the state of the button changes
Parameter
key
Explanation
Indicates which state change called the function
0: Button was released
1: Button was pressed
Rev. 01
157
12.3.18.3 Functions
native Switch_Init(mode, funcidx=-1);
Initialises the solenoid switch
Parameter
mode
Explanation
Selection of whether the solenoid switch is evaluated by the firmware or script
SWITCH_MODE_
INTERNAL :
If the button was pressed and held for 3 sec., a
transmission is initiated when the button is
released.
SWITCH_MODE_SCRIPT : In the event of a state change of the button (press
or release), the public function, for which the
index was transferred to the "Switch_Init"
function, is called.
funcidx
Index of the public function that should be executed in the event of a state change
of the button (only necessary if mode=SWITCH_MODE_SCRIPT)
Type of function: public func(key);
Explanation
Return value
l
l
OK, if successful
< OK, if an error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84)
native Switch_Close();
Deactivates the solenoid switch. An action is no longer initiated when the button is pressed.
Explanation
Return value
l
l
158
OK, if successful
< OK, if an error occurs (see "Return codes for general purposes" in
chapter "Constants" on page 84)
Rev. 01
Chapter 12 Device Logic (Pawn)
12.3.19 Power management
Note: You require the following include file to be able to use the functions in this chapter: #include
<pm>
12.3.19.1 Arrays with symbolic indices
TPM_Info
Information on the energy source used and power management status
// BatteryType
//
// Flags
//
// VIn
// VBatt
// SOC
// PIn
// ChargingMode
//
// Description
PSU type (see "Type of power supply unit" in chapter
"Constants" on page 159)
Power management status (see "Power
management status" in chapter "Constants" on page 159)
Supply or charging voltage V IN in [mV]
Battery or rechargeable battery voltage in [mV]
State of charge in [0.01%]
Power consumption in [mW]
Charge mode (see "Charge mode" in chapter
"Constants" on page 159)
Designation of the power supply unit
#define TPM_Info[
.BatteryType, .Flags, .VIn, .VBatt, .SOC, .PIn,
.ChargingMode, .Description{16}
]
12.3.19.2 Constants
Charging mode
PM_CHARGING_OFF
= 0,
PM_CHARGING_NORMAL = 1,
PM_CHARGING_SOLAR = 2,
// Charge control deactivated
// charge, if state of charge <50%
// always charge when possible and
// sufficient input voltage (V IN > 16V ) is
available
Type of power supply unit
PM_BATT_TYPE_NONE
= 0,
PM_BATT_TYPE_NORMAL = 1,
PM_BATT_TYPE_LIIO
= 2,
// No battery or external power supply
// Battery, only discharged
// li-ion rechargeable battery
Power management status
PM_FLAG_CHARGING
PM_FLAG_BACKUP
PM_FLAG_ERROR
Rev. 01
= 0x00000001, // Charge control active
= 0x00000002, // Supply via internal energy source
// following failure of V IN (only if
// V IN monitoring was activated)
= 0x00000008, /* Power management error (does not charge,
SoC cannot be determined, because
the memory of the power supply unit
could not be read, for example) */
159
Configuration of the Coulomb counter (electric charge)
Configuration flags for the PM_GetCoulombCounter() function
PM_CC_RESET
= 0x00000001,
/* Reset Coulomb counter that can be used
for the application */
12.3.19.3 Callback functions
public func();
Function to be provided by the script developer, that is called up if a failure of the supply or charging
voltage V IN has been detected
12.3.19.4 Functions
native PM_SetChargingMode(mode);
Sets the charge mode. Detailed information on the charge control is provided in chapter "Technical
details about energy management" on page 61.
Parameter
mode
PM_CHARGING_OFF :
Explanation
Charge control deactivated
PM_CHARGING_NORMAL :
Charge if the state of charge of the
rechargeable battery is <50%.
PM_CHARGING_SOLAR :
Charge continuously, if possible, and the
supply or charging voltage V IN is above 16V
Explanation
Return value
l
l
OK, if successful
ERROR, if an invalid parameter was transferred
native PM_BackupInit(funcidx);
Activates malfunction monitoring for the supply or charging voltage V IN and specifies the function that
should be called up in the event of the supply or charging voltage V IN failing
Parameter
funcidx
Explanation
Index of the public function that should be called up if a failure of the supply or
charging voltage V IN has been detected
Type of function: public func();
Explanation
Return value
l
l
160
OK, if successful
ERROR, if an invalid parameter was transferred
Rev. 01
Chapter 12 Device Logic (Pawn)
native PM_BackupClose();
Deactivates malfunction monitoring for the supply or charging voltage V IN
Explanation
Return value
OK, if successful
native PM_GetInfo(info[TPM_Info], len=sizeof info);
Provides information on the energy source used and power management status
Parameter
info
Explanation
Structure for storing the information (see "TPM_Info" in chapter "Arrays with
symbolic indices" on page 159)
len
Size (in cells) of the structure to store the information - OPTIONAL
Explanation
Return value
l
l
OK, if successful
ERROR, if an invalid parameter was transferred
native PM_GetCoulombCounter(flags=0);
Reads the current state of the Coulomb counter (electric charge) that can be used for the application
derived from the system's internal Coulomb counter
Parameter
flags
Explanation
Configuration flags to be set/deleted - OPTIONAL
Bit0: Resetting the Coulomb counter that can be used for the application
0 = no action
PM_CC_RESET = Counter reset
Return value
Explanation
Depleted electric charge [mAs] since the last reset of the Coulomb counter that
can be used for the application
12.4 Device Logic error codes
If an error occurs while executing the Device Logic, the corresponding error code is entered in the device log
and the Device Logic is restarted. If such an error occurs more than three times in 24 hours, the Device Logic
is deactivated and error handling is activated (see "Error handling" on page 32). The parameter for all log
entries except "SCRIPT_ERR" contains the 32-bit instruction pointer of the PAWN abstract machine (AMX).
Two entries are generated in the device log as only 16-bit values can be saved in the parameter of a log entry.
The first entry contains Bit31-Bit16 and the second entry contains Bit15-Bit0 of 32-bit instruction pointer.
Rev. 01
161
Log entry
Code
Plain text
3000 SCRIPT_ERR
Parameter
Code
Plain text
0
NO SCRIPT
No valid Device Logic available
1
SCRIPT UPDATE
New Device Logic received
2
SCRIPT EXCEPT
LOOP
Exception loop detected (4 system starts due to
exception within 10 min.)
Description
The Device Logic is deactivated and error
handling is activated (see "Error handling" on
page 32). The file system is also reformatted.
This means that all of the data and log entries
recorded to date are deleted. This is indicated by
the additional "LOG REFORMATFILE" log entry.
3
SCRIPT SOFT
ERROR 1
First time a runtime error has occurred within
24 hours. Device Logic was restarted.
4
SCRIPT SOFT
ERROR 2
Second time a runtime error has occurred within
24 hours. Device Logic was restarted.
5
SCRIPT SOFT
ERROR 3
Third time a runtime error has occurred within
24 hours. Device Logic was restarted.
The Device Logic is deactivated and error
handling is activated if another runtime error
should occur within 24 hours (see "Error
handling" on page 32).
6
SCRIPT UPDATE
ERROR
Connection abort during the Device Logic
download
As the existing Device Logic is located in the
RAM, it can continue to be executed until the
next PowerOn. It can no longer be executed
following a PowerOn and the "SCRIPT_ERR,
NO SCRIPT" error is entered in the device log.
3001 AMX_ERR_EXIT
##
---
Abortion
e.g. max. number of PAWN commands
(100,000) per run reached
3002 AMX_ERR_
ASSERT
##
---
Assertion failed
3003 AMX_ERR_
STACKERR
##
---
Stack/heap collision (insufficient stack size)
3004 AMX_ERR_
BOUNDS
##
---
Array index outside the valid range
3005 AMX_ERR_
MEMACCESS
##
---
Invalid memory access
162
e.g. mix-up between cell (32-bit element) access
[] and byte access {}
Rev. 01
Chapter 12 Device Logic (Pawn)
Log entry
Code
Plain text
3006 AMX_ERR_
INVINSTR
Parameter
Code
Plain text
##
---
Invalid statement
3007 AMX_ERR_
STACKLOW
##
---
Stack underflow
3008 AMX_ERR_
HEAPLOW
##
---
Heap underflow
3009 AMX_ERR_
CALLBACK
##
---
No (invalid) native callback function
3010 AMX_ERR_NATIVE ##
---
Native function failed
3011 AMX_ERR_DIVIDE ##
---
Divide by zero
3012 AMX_ERR_SLEEP ##
---
Sleep mode
3013 AMX_ERR_
INVSTATE
##
---
Invalid state
3016 AMX_ERR_
MEMORY
##
---
Out of memory
3017 AMX_ERR_
FORMAT
##
---
P-code file format is invalid/not supported
3018 AMX_ERR_
VERSION
##
---
File is for a newer version of AMX
3019 AMX_ERR_
NOTFOUND
##
---
File or function not found
3020 AMX_ERR_INDEX
##
---
Invalid index parameter (invalid entry point)
3021 AMX_ERR_DEBUG ##
---
Debugger cannot be executed
3022 AMX_ERR_INIT
##
---
AMX not initialised (or initialised twice)
3023 AMX_ERR_
USERDATA
##
---
User data field cannot be set (table full)
3024 AMX_ERR_INIT_
JIT
##
---
JIT cannot be initialised.
3025 AMX_ERR_
PARAMS
##
---
Faulty parameter
3026 AMX_ERR_
DOMAIN
##
---
Domain error. The result of the expression is not
in the valid range.
3027 AMX_ERR_
GENERAL
##
---
General error (invalid or non-specific error)
3028 AMX_ERR_
OVERLAY
##
---
Overlays are not supported (JIT) or are not
initialised.
Description
3014 reserved
3015 reserved
Rev. 01
163
12.5 Syntax
12.5.1 General syntax
12.5.1.1 Format
Identifiers, numbers and characters are separated by spaces, tabs, line breaks and "form feed". A series of
one or more of these separators is recognised as an empty space.
12.5.1.2 Optional semicolons
Semicolons (used to finish a statement) are optional if they are at the end of a line. Semicolons are required to
separate several statements in a line. An expression can be split across several lines, though the postfix
operators must be on the same line as the operand.
12.5.1.3 Comments
Text between the /* and */ symbols (both symbols can be on the same or different lines) and text following //
(to the end of the line) are comments. Comments must not be nested. The compiler considers comments to
be blank space. A documentation comment is a comment that starts with "/** " (two stars and space after the
second star) and ends with "*/". A comment that starts with "/// " (three forward slashes and a space after the
third slash) is also a documentation comment. The parser can support the documentation comment in
different ways, for example, by using it to generate online help.
12.5.1.4 Identifier
Names of variables, functions and constants. Identifier comprises the characters a...z, A...Z, 0...9, _ or @.
The first character must not be a number. The characters @ and _ on their own are not valid identifiers, e.g.
"_Up" is a valid identifier but "_" is not. Pawn distinguishes between upper and lower case. The parser cuts
identifiers off after a certain length. By default, only the first 16 characters are referenced for distinguishing
purposes.
12.5.1.5 Reserved keywords
Statements
assert
break
case
continue
default
do
else
exit
for
goto
if
return
sleep
state
switch
while
164
Operator
defined
sizeof
state
tagof
Directives
defined
sizeof
state
tagof
Others
defined
sizeof
state
tagof
Rev. 01
Chapter 12 Device Logic (Pawn)
12.5.1.6 Numerical constants
12.5.1.6.1 Numerical integer constants
Binary
0b followed by a series of 0 and 1
Decimal
A series of numbers between 0 and 9
Hexadecimal
0x followed by a series of numbers between 0 and 9 and the letters a to f
12.5.1.6.2 Numerical floating-point constants
A floating-point number is a number with numbers after the decimal point. A floating-point number starts with
one or several numbers, includes a decimal point and has at least one number after the decimal point, e.g.
"12.0" and "0.75" are valid floating-point numbers. An exponent can optionally be added. The notation is the
letter "e" (lower case) followed by an integer numerical constant. For example, "3.12e4" or "12.3e-3" are valid
floating-point numbers with an exponent.
12.5.2 Variables
12.5.2.1 Declaration
The keyword "new" declares a new variable. For special declarations, the keyword "new" is replaced with
"static" (see "Static local declaration" on page 166). The value of the new variable is zero, provided that is not
initialised explicitly.
A variable declaration can appear
At every position at which an expression is valid - local variable
l At every position at which a function declaration or the implementation of the function is valid - global
variables
l In the first expression of a "for" loop (see "For (expression 1; expression 2; expression 3) statement " on
page 176) - local variable
l
Example:
new a;
// without initialisation (value is 0)
new b = 3; // with initialisation (value is 3)
12.5.2.2 Local declaration
A local declaration appears within a statement block. A variable can only be accessed within this block and
the blocks that it comprises. A declaration within the first expression of a loop instruction is also a local
declaration.
12.5.2.3 Global declaration
A global declaration appears outside of a function and a global variable can be used in any function. Global
variables can only be initialised with constant expressions.
Rev. 01
165
12.5.2.4 Static local declaration
A local variable is destroyed if the execution leaves the block in which the variable was created. Local
variables in a function only exist during the operating time of the specified function. Each new call up of the
function creates and initialises new local variables. The variable will also remain in the memory at the end of
the function, if a local variable is declared with the keyword "static" instead of "new". This means that static,
local variables provide permanent private storage that can only be accessed by a single function (or block).
Static local variables can only be initialised with constant expressions, the same way as global variables.
12.5.2.5 Static global declaration
A static global variable acts in the same way as a global variable with the difference that the variable is only
valid in the file in which it was declared. Replace the keyword "new" with "static" to declare a global variable
as static.
12.5.2.6 Floating point values
The pawn supports floating point values. These can be added at every point at which a variable declaration is
valid.
Example:
new Float:a;
// without initialisation (value is 0.0)
new Float:b = 3.0; // with initialisation (value is 3.0)
12.5.3 Constant variables
It is sometimes necessary to create a variable that is initialised once and is then not meant to be changed
again. Such a variable acts in a similar way to a symbolic constant although it is still a variable. To declare a
constant variable, place the keyword "const" between the keyword that starts the variable declaration ("new",
"static") and the name of the variables.
Example:
new const address[4] = { 192, 0, 168, 66 }
static const status /* initialised to zero */
Typical situations in which you could use a constant variable, include:
l
l
To create an "array" constant. Symbolic constants cannot be accessed via the index.
It is a special case when array arguments are marked as "const" in a function. Arrays arguments are
always transferred via a reference. If the arguments are declared to be "const", they are protected
against unwanted changes. See examples of "const function arguments" in the chapter "Function
arguments ("call-by-value" versus "call-by-reference")" on page 179.
12.5.4 Array variables
12.5.4.1 One-dimensional arrays
The name[constant] syntax declares the name as an array of "constant" elements, where each element is an
entry. "name" is a placeholder for the name of the variable and "constant" is a positive value not equal to zero.
"constant" is optional and can be omitted. If there is no value between the brackets, the number of elements is
equal to the number of initial values. The array index area is "zero-based", which means that the first element
is "name[0]" and the last element is "name[constant-1]".
166
Rev. 01
Chapter 12 Device Logic (Pawn)
12.5.4.2 Initialisation
Data objects can be initialised during their declaration. The initialised value from global data objects must be a
constant value. Global or local arrays must also be initialised with constant values. Data that is not initialised
are zero by default.
Example:
List: valid declaration
new i = 1
new j
new k = ’a’
new a[] = [1,4,9,16,25]
new s1[20] = [’a’,’b’]
new s2[] = ’’Hello world...’’
/* j is 0 */
/* k has the character code of ’a’ */
/* a has 5 elements */
/* the remaining 18 elements are 0 */
/* an unpacked string */
List: invalid declaration
new c[3] = 4
new i = "Good-bye"
new q[]
new p[2] = { i + j, k - 3 }
/* An array cannot be set to an individual
value */
/* only an array can hold a string */
/* Unknown size for an array */
/* Array initialisers must be constants */
12.5.4.3 Progressive initialisation for arrays
The point operator continues the initialisation of the arrays based on the last two initialised values. The point
operator (three points, "...") initialises the array up to the array limit.
Example: List: array initialisers
new a[10] = { 1, ... }
new b[10] = { 1, 2, ... }
new c[8] = { 1, 2, 40, 50, ... }
new d[10] = { 10, 9, ... }
// sets all of the elements to 1
// b = 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
// c = 1, 2, 40, 50, 60, 70, 80, 90
// d = 10, 9, 8, 7, 6, 5, 4, 3, 2, 1
12.5.4.4 Multi-dimensional arrays
(Only arrays with up to three dimensions are supported)
Multi-dimensional arrays are arrays that include references to other sub-arrays. For example, a twodimensional array is an "array on one-dimensional arrays".
Example for the declaration of two-dimensional arrays:
new a[4][3]
new b[3][2] = [ [ 1, 2 ], [ 3, 4 ], [ 5, 6 ] ]
new c[3][3] = [ [ 1 ], [ 2, ...], [ 3, 4, ... ] ]
new d[2]{10} = [ "agreement", "dispute" ]
new e[2][] = [ ’’OK’’, ’’Cancel’’ ]
new f[][] = [ ’’OK’’, ’’Cancel’’ ]
Rev. 01
167
As the last two declarations (variables "e" and "f") illustrates, the last dimension has an unspecified length. In
this case, the length of the sub-array is detected by the associated initialiser. Each sub-array is a different
length. In this specific example, "e[1][5]" includes the letter "l" of the word "Cancel". However, "e[0][5]" is
invalid as the sub-array e[0] only comprises three entries (the letters "O", "K" and the zero terminator). The
difference between the declarations of the "e" and "f" arrays is that we enable the compiler to determine the
number of higher dimensions for "f". "sizeof f" and "sizeof e" are both 2 (see "Arrays and the "sizeof" operator"
on page 168).
12.5.4.5 Arrays and the "sizeof" operator
The "sizeof" operator returns the number of elements of a variable. The "sizeof" result of a simple (non array)
variable is always 1.
An array with one dimension comprises a number of elements and the "sizeof" operator returns this quantity.
The code section below would therefore issue "5", as the array comprises four characters and the zero
terminator.
new msg[] = ’’Help’’
printf(’’%d’’, sizeof msg);
The "sizeof" operator always returns the number of entries even for a "packed" array. The code section below
also issues "5", as the variable comprises five entries even though it requires less memory space.
new msg{} = "Help"
printf(’’%d’’, sizeof msg);
For multi-dimensional arrays, the "sizeof" operator can return the number of elements for every dimension.
An element in the last (lowest) dimension is a single entry, while it is a sub-array in the highest dimension.
Please note that in the following code section, the "sizeof matrix" syntax returns the number of elements of the
higher dimension and that the "sizeof matrix[]" syntax issues the lower dimension of the two-dimensional
array. The code section issues three (higher dimension) and two (lower dimension).
new matrix[3][2] = { { 1, 2 }, { 3, 4 }, { 5, 6 } }
printf(’’%d %d’’, sizeof matrix, sizeof matrix[]);
The application of the "sizeof" operator on multi-dimensional arrays is particularly practical when it is used as
a standard value for function arguments.
168
Rev. 01
Chapter 12 Device Logic (Pawn)
12.5.5 Operators and expressions
12.5.5.1 Notational conventions
The use of some operators is dependent on the relevant type of operand. The following notations are
therefore used in this chapter:
e
Any expression
v
Any expression that can be assigned a value ("lvalue" expression - variable)
a
An array
f
A function
s
A symbol - this can be a variable, a constant or a function
12.5.5.2 Expressions
An expression consists of one or several operands with an operator. The operand can be a variable, a
constant or another expression. An expression followed by a semicolon is a statement.
Examples of expressions:
v++ f(a1, a2)
v = (ia1 * ia2) / ia3
12.5.5.3 Arithmetic
Operator Example
+
e1 + e2 Result of adding e1 and e2
-
Explanation
e1 - e2
Result of subtracting e2 from e1
-e
Result of the arithmetic negation of e (two's complement)
*
e1 * e2
Result of multiplying e1 with e2
/
e1 / e2
Result of dividing e1 by e2. The result is truncated to the closest whole number that is
less or equal to the quotient. Positive and negative values are rounded down (negative
infinity).
%
e1 % e2
Result is the remainder of the division of e1 by e2. The prefix is the same as that of e2
++
v++
Increases v by 1. The result of the expression is the value before the increase.
++v
Increases v by 1. The result of the expression is the value following the increase.
v--
Decreases v by 1. The result of the expression is the value before the decrease.
--v
Decreases v by 1. The result of the expression is the value following the decrease.
--
Note: The unary + is not defined in the pawn. The operators ++ and -- change the operand. The
operand must be a "lvalue".
Rev. 01
169
12.5.5.4 Bit manipulation
Operator Example
Explanation
~
~e
The result is the one's complement of e.
>>
e1 >> e2 The result of the arithmetic shift to the right of e1 by e2 bits. The shift is signed: The bit
on the far left is copied to the free bits of the result.
>>>
e1 >>>
e2
<<
e1 << e2 Result: Shift to the left of e1 by e2 bits. The free bits of the result are filled with 0. There
is no difference between an arithmetic and a logical shift to the left.
&
e1 & e2
The result is the bitwise logical "and" of e1 and e2.
|
e1 | e2
The result is the bitwise logical "or" of e1 and e2.
^
e1 ^ e2
The result is the bitwise logical "exclusive or" of e1 and e2.
The result of the logical shift to the right of e1 by e2 bits. The shift is unsigned. The free
bits of the result are filled with 0.
12.5.5.5 Assignment
The result of an assignment expression is the value of the operand following the assignment.
Operator Example
Explanation
=
v=e
Assigns the value of e to the variable v
v=a
Assigns the array a to variable v. v must be an array of the same size and with the
same dimensions as a. a can be a character string or an array.
Note: The following operators combine an assignment with an arithmetic or bitwise operation. The
result of the expression is the value of the left operand following the arithmetic or bitwise operation.
Operator Example
+=
v += e
Increases v by e
Explanation
-=
v -= e
Decreases v by e
*=
v *= e
Multiplies v with e
/=
v /= e
Divides v by e
%=
v %= e
Assigns v the remainder of the division of v and e
>>=
v >>= e
Arithmetically shifts v to the right by e bits
>>>=
v >>>= e Logically shifts v to the right by e bits
<<=
v <<= e
Shifts v to the left by e bits
&=
v &= e
Executes a bitwise "and" from v and e and assigns the result to v
|=
v |= e
Executes a bitwise "or" from v and e and assigns the result to v
^=
v ^= e
Executes a bitwise "exclusive or" from v and e and assigns the result to v
170
Rev. 01
Chapter 12 Device Logic (Pawn)
12.5.5.6 Comparative operators
A logical "false" is represented by an integer value of 0; a logical "true" is represented by a value that is not 0.
Results of a comparative expression are either 0 or 1 and the "tag" is set to "bool".
Operator Example
Explanation
==
e1 == e2 The result is "true" if e1 and e2 are the same.
!=
e1 != e2
The result is "true" if e1 and e2 are not the same.
Note: The following operators can be linked, the same as in the expression "e1 <= e2 <= e3". This
means that the result is "1" if every single comparison is true and "0" if at least one comparison is false.
Operator Example
Explanation
<
e1 < e2 The result is a logical "true" if e1 is less than e2.
<=
e1 <= e2 The result is a logical "true" if e1 is less or equal to e2.
>
e1 > e2
>=
e1 >= e2 The result is a logical "true" if e1 is greater or equal to e2.
The result is a logical "true" if e1 is greater than e2.
12.5.5.7 Boolean
A logical "false" is represented by an integer value of 0; a logical "true" is represented by a value that is not 0.
Results of a comparative expression are either 0 or 1 and the "tag" is set to "bool".
Operator Example
Explanation
!
!e
The result is a logical "true", if e is logical "false".
||
e1 || e2
&&
e1 && e2 The result is "true" if e1 and e2 are logical "true". The expression e2 is only evaluated if
e1 is logical "true".
Rev. 01
The result is "true", if either e1 or e2 (or both) are logical "true". The expression e2 is
only evaluated if e1 is logical "false".
171
12.5.5.8 Other
Operator
Example
[]
a[e]
Explanation
Array index: The result is the entry at position e of array a.
{}
a{e}
Array index: The result is the index at position e of "packed" array a:
()
f(e1, e2, ... eN)
The result is the value that is returned by function f. The function is called up
with parameters e1, e2, ... eN. The sequence of the evaluation of the
parameters is not defined. (The implementation of the script engine may
evaluate the parameters in reverse order.)
?:
e1 ? e2 : e3
The result is either e2 or e3, depending on the value of e1. The conditional
expression is a composite expression with a two-part operator, "?" and ":".
The expression e2 is evaluated if e1 is logical "true"; e3 is evaluated if e1 is
logical "false".
:
tagname: e
"Tag" overwritten: The value of the expression does not change, although
the "tag" does change.
defined
defined s
Result is "1" if the symbol was defined. The symbol can be a constant or a
global or local variable. The "tag" of the expression is "bool"
sizeof
sizeof s
The result is the number of elements of the specified variable. An element
is an entry for simple variables and for one dimensional arrays. For multidimensional arrays, the result is the number of elements (sub-arrays) in the
highest dimension. Add [] to the name of the array to specify a lower
dimension. The result is 0 if the size of the variable is not known. If this
operator is used in a "default" value of a function, the expression is
executed at the time that the function was called up and not at the time that
the definition was completed.
tagof
tagof s
The result is a unique number that represents the "tag" of the variables, the
constants, the return value of a function or the name of the "tag" title. If this
operator is used in a "default" value of a function, the expression is
executed at the time that the function was called up and not at the time that
the definition was completed.
12.5.5.9 Priority of the operators
The following table groups the operators with the same priority, starting with the highest priority at the top of
the table.
If the evaluation of an expression is not explicitly justified with brackets, it is categorised by the association
rules. For example: a*b/c is equal to (a*b)/c based on the left to right association, and a=b=c is equal to
a=(b=c).
172
Rev. 01
Chapter 12 Device Logic (Pawn)
Operator
()
Function call
[]
array index (element)
{}
array index (character)
Explanation
Reading order
left-to-right
!
~
++
-:
defined
sizeof
tagof
logical not
one's complement
two's complement (unary minus)
increase
decrease
"tag" overwritten
symbol definition status
symbol size in "elements"
unique number of the tag
right-to-left
*
/
%
multiplication
division
modulo
left-to-right
+
-
addition
subtraction
left-to-right
>>
>>>
<<
arithmetic shift to the right
logical shift to the right
shift to the left
left-to-right
&
bitwise "and"
left-to-right
^
bitwise "exclusive or"
left-to-right
|
bitwise "or"
left-to-right
<
<=
>
>=
less than
less or equal to
greater than
greater or equal to
left-to-right
==
!=
equal
unequal
left-to-right
&&
logical "and"
left-to-right
||
logical "or"
left-to-right
?:
conditional execution
right-to-left
=
Assignment
*= /= %= += -= >>= >>>= <<= &= ^= |=
right-to-left
,
comma
left-to-right
12.5.6 Statements
A statement can comprise one or several lines. A line can comprises two or more statements.
Statements for the sequence control (if, if-else, for, while, do-while and switch) can be nested.
12.5.6.1 Statement label
A label consists of an identifier followed by a ":". A label is a "Jump target" of a "goto" statement.
Rev. 01
173
Each statement can be marked with a label. The label must be followed by a statement, which can also be an
"empty statement".
The scope of a label is the function in which it was declared, i.e. a "goto" statement cannot jump from the
current function to another function.
12.5.6.2 Composite statements
A composite statement (also known as a block) is a series of zero or several statements that is enclosed by
brackets ("{" and "}"). The closing bracket ("}") must not be followed by a semicolon. Each statement can be
replaced by a block. A composite statement that does not comprise any statements is a special case and is
known as an "empty statement".
12.5.6.3 Expression statement
Each expression becomes a statement when a semicolon (";") is added. An expression also becomes a
statement, if the expression is only followed by blank spaces to the end of the line, and the expression is not
continued in the next line.
12.5.6.4 Empty statement
An empty statement does not execute any statements and consists of a block statement without statements,
i.e. it consists of the "{ }" symbol. Empty statements are implemented in control flow statements without
actions (e.g. "while (!iskey()) {}") or if a label is defined exactly before the closing bracket of a block statement.
An empty statement does not end with a semicolon.
12.5.6.5 Assert expression
The program is aborted with a runtime error if the expression is logical "false"
Note: This expression protects against "impossible" or invalid conditions. In the following example, a
negative fibonacci number is invalid. The assert statement marks this error as a programming error.
Assert statements should only ever highlight programmer errors and never user inputs.
Example:
fibonacci(n)
{
assert n > 0
new a = 0, b = 1
for (new i = 2; i < n; i++)
{
new c = a + b
a = b
b = c
}
return a + b
}
174
Rev. 01
Chapter 12 Device Logic (Pawn)
12.5.6.6 Break
Terminates and leaves the smallest, encircling "do", "for" or "while" statement at any point in the loop. The
"break" statement moves the program flow to the next statement outside the loop.
Example:
example(n)
{
new a = 0
for(new i = 0; i < n ; i++ )
{
a += i
if(i>10)
break
a += 1
}
return a
}
12.5.6.7 Continue
Terminates the current iteration of the smallest encircling "do", "for" or "while" statement and moves the
program control to the conditional part of the loop.
Example
example(n)
{
new a = 0
for(new i = 0; i < n ; i++ )
{
a += i
if(i>10)
continue
a += 1
}
return a
}
Rev. 01
175
12.5.6.8 Do statement while (expression)
Executes a statement before the conditional part (the "while" condition) is evaluated. The statement is
repeated as long as the condition is logical "true". The statement is executed at least once.
Example:
example(n)
{
new a = 0
do
{
a++
}
while(n >= 0)
return a
}
12.5.6.9 Exit expression
Cancels the program. The expression is optional, however, if present it must start and end on the same line
as the "exit" statement. The exit statement returns the expression value or zero to the main application, if no
expression is specified.
12.5.6.10 For (expression 1; expression 2; expression 3) statement
All three of the expressions are optional.
Expression 1:
Is only evaluated once before entering the loop. This expression can be used to initiate a variable. This
expression also includes the variable declaration by means of the "new" syntax. A variable that is
declared at this stage is only valid in the loop. It is not possible to combine an expression (with existing
variables) and a declaration of new variables in this field. All of the variables must either already exist in
this field, or they must all be declared in this area.
Expression 2:
This expression is executed before every run of the loop and terminates the loop if the expression
logical "false" is returned. If this expression is omitted, it is assumed that the result of expression 2 is
logical "true".
Expression 3:
This expression is executed each time the statement is completed. The program control moves from
expression 3 to expression 2 for the next (conditional) iteration of the loop.
176
Rev. 01
Chapter 12 Device Logic (Pawn)
Example:
example(n)
{
new a = 0
for(new i = 0; i < n; i++)
{
a++
}
return a
}
The "for ( ; ; )" statement is the same as the "while (true)" statement.
12.5.6.11 Goto label
Moves the program control (unconditionally) to the statement that follows the specified label. The label must
be within the same function as the "goto"-statement (a "goto"-statement cannot jump out of a function).
12.5.6.12 If (expression) statement 1 else statement 2
Executes statement 1 if the results of the expression is logical "true". The "else"clause of the "if" statement is
optional. If the result of the expression is logical "false" and there is an "else" clause, the statement that is
associated with the "else" clause (statement 2) is executed.
Example:
example(n)
{
if(n < 0)
return -1
else if (n == 0)
return 0
else
return 1
}
12.5.6.13 Return expression
Terminates the current function and moves the program control to the next statement following the function
call. The expression value is returned as the function result. The expression can be an array or a character
string. The expression is optional, however, if present it must start on the same line as the "return" statement.
Zero is returned if no expression is specified.
12.5.6.14 switch (expression) {case list}
Transfers the sequence control to the various statements within the "switch", depending on the value of the
"switch" expression. The main part of the "switch" statement is a composite statement that comprises a series
of "case" clauses. Each "case" clause starts with the keyword "case" followed by a list of constants and a
statement. The list of constants is a series of expressions separated by commas, each of which is evaluated
as a constant value. This list ends with a colon. To specify an area in this list, separate the lower and upper
limit of the area with a double point (".."). An example for an area is: "case 1..9:".
Rev. 01
177
The "switch" statement shifts the sequence control to a "case" clause if a value from the list corresponds to the
value of the "switch" expression.
The "default" clause consists of the "default" keyword and a double point. The "default" clause is optional,
however, if it is specified it must be included as the last entry in the "case" list. The "switch" statement shifts
the sequence control to the "default" clause if none of the "case" clauses comply with the "switch" expression.
Example:
example(n)
{
new a = 0
switch (n)
{
case 0..3:
a = 0
case 4,6,8,10:
a = 1
case 5,7:
a = 2
case 9:
a = 3
default:
a = -1
}
return a
}
12.5.6.15 While (expression) statement
Evaluates the expression and executes the statement if the result of the expression is logical "true". The
program control returns to the expression again once the statement has been executed. The statement is
therefore executed as long as the expression is logical "true".
Example:
example(n)
{
new a = 0
while(n >= 0)
{
a++
}
return a
}
178
Rev. 01
Chapter 12 Device Logic (Pawn)
12.5.7 Functions
A function declaration specifies the name of the function and the formal parameters enclosed in brackets. A
function can also return a value. A function must be defined globally, i.e. declared outside of another function
and is globally available.
If the function declaration is followed by a semicolon (instead of a statement), this is a forward declaration of a
function.
The "return" statement sets the return value of the function. For example, the return value of the "sum"
function (see below) is the sum of both parameters. The "return" expression is optional.
sum(a, b)
{
return a + b
}
The arguments of a function are (declared implicitly) local variables for this function. The function call specifies
the values of the arguments. Another example of a complete definition of a function is "leap year" that
indicates "true" or "false" for the relevant year.
leapyear(y)
{
return y % 4 == 0 && y % 100 != 0 || y % 400 == 0
}
Details of the statements used in this example are provided in the chapter "Operators and expressions" on
page 169.
Generally, functions include local variable declarations and consist of a block statement.
Note: In the next example, the "assert" statement prevents negative values for the exponent.
power(x, y)
{
/* returns xy */
assert y >= 0
new r = 1
for (new i = 0; i < y; i++)
r *= x
return r
}
A function can comprise several "return" statements, for example, one is used to quickly terminate a function if
invalid parameters are transferred, or when it becomes apparent that the function has nothing to do. If a
function returns an array, all of the "return" statements must return an array with the same number of entries.
12.5.7.1 Function arguments ("call-by-value" versus "call-by-reference")
The "faulty" function in the next example has a parameter that is used in the loop to calculate the factorial of
this number. It must be noted that the function modifies the argument.
Rev. 01
179
main()
{
new v = 5
new f = faculty(v)
}
faculty(n)
{
assert n >= 0
new result = 1
while (n > 0)
result *= n-return result
}
Regardless of what (positive) value the "n" variable has at the start of the "while" loop, "n" will equal zero at
the end of the function. In the "faculty" function, for example, the parameter is transferred as a value ("by
value"), which means that changes to the "n" variable are only valid locally in the "faculty" function. In other
words, the "v" variable in the "main()" function has the same value before and after the function is called up.
Arguments can be transferred as a value ("by value") or as a reference ("by reference"). A function argument
that is to be transferred as a reference must have the "&" prefix preceding the name. The arguments are
transferred to the function as a value by default.
Example:
swap(&a, &b)
{
new temp = b
b = a
a = temp
}
To transfer an array to a function, add a pair of brackets ("[]") to the name of the argument. The number of
entries can also be specified. This improves the error detection of the compiler's parser.
Example:
addvector(a[], const b[], size)
{
for (new i = 0; i < size; i++)
a[i] += b[i]
}
Arrays are always transferred as a reference.
Note: The "b" array in the above-mentioned example is not changed in the function. This function
argument was declared as a "const" to make this explicit. In addition to the improved error detection, it
also enables the compiler to generate a more efficient code.
180
Rev. 01
Chapter 12 Device Logic (Pawn)
The following code example calls up the "addvector" function and adds five to each element of the "vect"
variables:
new vect[3] = [ 1, 2, 3 ]
addvector(vect, [5, 5, 5], 3)
/* vect[] now comprises the values 6, 7 and 8 */
12.5.7.2 Named parameters versus fixed parameters
In the previous examples, the order of the parameters in a function call were important as each parameter
was copied to the same position of the function parameter. For example, in the "weekday" function (defined
below), the expression "weekday(12 ,31, 1999)" would be used to get the weekday of the last day of the last
century.
weekday(month, day, year)
{
/* returns the day of the week: 0=Saturday, 1=Sunday, etc. */
if (month <= 2)
month += 12, --year
new j = year % 100
new e = year / 100
return (day + (month+1)*26/10 + j + j/4 + e/4 - 2*e) % 7
}
The date format changes depending on the culture and country, while the USA use the month/day/year
format, European countries frequently use the day/month/year format and technical publications use the
year/month/day (ISO/IEC 8824) format. In other words, the sequence of the parameters is not "standardised"
or "normal". For this reason, there is an alternative way of transferring parameters to a function, by using
"named parameters". These are illustrated in the next example (the function was declared in the same way as
the previous example).
new wkday1 = weekday( .month = 12, .day = 31, .year = 1999)
new wkday2 = weekday( .day = 31, .month = 12, .year = 1999)
new wkday3 = weekday( .year = 1999, .month = 12, .day = 31)
In "named parameters", a dot (".") precedes the name of the argument. The argument of the function can be
set to any expression that is valid for the argument. In the event of a named parameter, the equals sign ("=")
does not refer to an allocation but instead links the expression with a function argument.
Fixed and named parameters can be mixed together, although the fixed parameters must be specified before
the named parameters.
12.5.7.3 Standard values of function arguments
A function argument can have a standard value. The standard value of a function argument must be a
constant. To specify a standard value, add an equals sign ("=") and the value to the name of the parameter.
The standard value is adopted if a placeholder is specified instead of a valid function parameter during a
function call. The placeholder is the underscore character ("_"). The argument placeholder is only valid for
parameters with a standard value.
The right argument placeholders can be removed from the list of arguments.
Rev. 01
181
For example, if the "increment" function is defined as follows:
increment(&value, incr=1)
{
value += incr
}
The following function calls are all the same:
increment(a)
increment(a, _)
increment(a, 1)
Standard values for arguments that are transferred as a reference are helpful in making these parameters
optional. For example, if the "divmod" function was written to return the quotient and the rest as a parameter.
divmod(a, b, &quotient=0, &remainder=0)
{
quotient = a / b
remainder = a % b
}
Based on the previous definition of the "divmod" function, the following function calls are all valid:
new p, q
divmod(10, 3, p, q)
divmod(10, 3, p, _)
divmod(10, 3, _, q)
divmod(10, 3, p)
divmod 10, 3, p, q
The next example adds the value of an array to another one. The values of the array are increased by one if
only one parameter is specified:
addvector(a[], const b[] = {1, 1, 1}, size = 3)
{
for (new i = 0; i < size; i++)
a[i] += b[i]
}
12.6 Differences to C
l
l
182
The pawn is missing the input mechanism of C and is an "integer-only" variant of C. There are no
structures or unions. Floating point support must be implemented with user-defined operators and the
help of native functions.
The syntax for floating point values is stricter than that in C. Values such as ".5" and "6." are acceptable
in C but must be written as "0.5" and "6.0" in the pawn. The decimal point is optional in C. If an
exponent is included, then you can write "2E8" in C, however the pawn will not accept the capital letter
"E". Use the lower case letter "e". It requires a comma: e.g. "2.0e8" (see "Numerical constants" on
page 165).
Rev. 01
Chapter 12 Device Logic (Pawn)
l
l
l
l
l
l
l
l
l
l
l
l
The pawn does not support any "pointer". The pawn includes a "reference" argument to transfer
function parameters as a reference (see "Function arguments ("call-by-value" versus "call-byreference")" on page 179). The "placeholder" argument replaces some applications of the ZERO
pointer (see "Standard values of function arguments" on page 181).
Numbers can be specified in a hexadecimal, decimal or binary format. The octal format is not
supported (see "Numerical constants" on page 165). Hexadecimal numbers must start with "0x" ("x" in
lower case). The prefix "0X" is invalid.
"Cases" in a "switch"-statement are not "fall through". At least one statement must follow the "case"
label. You must create a composite statement (with {}) to execute several statements (see "switch
(expression) {case list}" on page 177). The "switch" statement is a "conditional goto" in C/C++. The
"switch" statement is a structured "if" in the pawn.
A "break" statement only terminates loops. In C/C++, the "break" statement also terminates a "case" in
a "switch" statement.
The pawn supports "array assignments" with the limitation that both of the arrays must be the same
length. For example, if "a" and "b" arrays have six lines, the expression "a=b" is valid. In addition to
character strings, the pawn also supports literal arrays and thus expressions such as "a = {0,1,2,3,4,5}"
where "a" is an array variable with six elements.
"defined" is an operator and not a preprocessor directive. The "defined" operator in the pawn works
with constants (declared with "const"), global variables, local variables and functions.
The "sizeof" operator returns the size of the variables in "elements" and not in "bytes". An element is an
entry or sub-array. Further details are provided in the chapter "Other" on page 172.
An empty statement is an empty block (with {}) and not a semicolon (see "Composite statements" on
page 174). This change prevents frequent errors.
A division is completed in such a way that the remainder of the division has (or ought to have) the same
prefix as the denominator. Divisions (operator "/") are always rounded down to the smaller whole
number (whereby -2 is smaller than -1). For example, 5/2 = 2 (2.5 is rounded down to 2), -5/2 = -3 (-2.5
is rounded down to -3). The "%" operator always generates a positive result regardless of the prefix of
the numerator (see "Operators and expressions" on page 169).
There is no unary "+" operator as it is a "no-operation" operator anyway ("a = +1" is not valid; correct: "a
= 1").
Three bit by bit operators have different priorities than in C. The priority level of the "&", "^" and "|"
operator is higher than the relational operators. Dennis Ritchie explains that these operators were
assigned a low priority level in C as early C compilers did not yet include the logical "&&" and "| |"
operators so that bit by bit "&" and "|" were used instead.
The keyword "const" in the pawn implements the "enum" functionality of C.
Rev. 01
183
l
184
In most cases, the forward declarations of functions (i.e. prototypes) are not necessary. A pawn is a
two-pass compiler. It detects all of the functions during the first cycle and uses them during the second.
User-defined operators must however be declared before use. If available, forward declarations must
be exactly the same as the definition of the function. The parameter names in the prototypes and the
definitions of the functions must be identical. The pawn attends to the parameter name in the prototype
due to the "named parameter" function. The pawn uses prototypes to call up the forward declared
functions. To use these with the named parameters during this process, the compiler must already
know the names of the parameters (and their position in the parameter list). The parameter names in
the prototypes must therefore match those in the definitions.
Rev. 01
Chapter 13 Data Descriptor
The basic principle of the myDatalogEASY IoTmini is "storage-2-storage" data transmission. For this type of
data transmission, neither the myDatalogEASY IoTmini nor the server must know about the logical content of
the data blocks. Therefore, the only aim is to transport a block of data from A to B.
The data transferred from the myDatalogEASY IoTmini to the sever can therefore be selected freely. There
are1024 Byte available per data record that can be used as required. There are also another 10 independent
memory blocks each with 4000 Byte for the configuration data that can be used as required.
The content of the data block or configuration block must be described on the server so that the data and
configurations received from the myDatalogEASY IoTmini can also be used within the myDatanet interface
(reports, visualisations, graphics, etc.). The Data Descriptor contains the tool for describing the data as well
as the correct provision of the data for use within the interface.
Rev. 01
185
Chapter 14 API
Chapter 14 API
Important note: The relevant licences are required on the myDatanet server to use the API
(Application Programming Interface). For future information contact your responsible sales partner.
14.1 Frontend API
The API is provided to export data from and import data to the myDatanet server. However, this is not just
limited to the pure measurement data but includes all of the data provided by myDatanet server (e.g.
configurations). It is therefore possible for the customer to completely dispense with the interface of the
myDatanet server and to create his own user interface. A specially developed PC program or web interface
can, for example, be used for this purpose.
14.2 rapidM2M Playground
The rapidM2M Playground enables you to familiarise yourself with the API of the myDatanet server and to
test the provided functions. One click on the "API" button will take you to rapidM2M Playground .
1 Opens the rapidM2M Playground
Rev. 01
187
14.2.1 Overview
rapidM2M Playground
1 Input field for the user name
2 Input field for the password
3 List of the available HTTP commands. The HTTP commands are grouped according to their fields of
application.
4 Depending on the selected HTTP command, the drop down lists for selecting the customer, user and
site that should replace the corresponding wild cards ("$CID"...customer , "$UID"...user, "$SID"...site) in
the resource path of the HTTP command are displayed.
5 Button to execute the HTTP command
6 Opens the website "http://rapidm2m.com/" that includes additional information for developers
7 Opens the login dialogue of the myDatanet server linked to the rapidM2M Playground
8 Opens the quick guide for the API
9 Button to change the colour scheme of the rapidM2M Playground
10 Window displaying the selected HTTP command
11 Response code sent by the myDatanet server as an answer to the HTTP command
12 Copies the JSON object generated as a response to the HTTP command on to the clipboard
13 Window displaying the documentation for the selected HTTP command. Depending on the selected
command, this includes a description of the action being executed, information that must be observed
and a description of the request body and response body.
14 Window displaying the JSON object that is generated as a response to the HTTP command
15 Window displaying the last executed HTTP commands
188
Rev. 01
Chapter 15 Maintenance
Chapter 15 Maintenance
Important note: To prevent any damage to the device, the work described in this section of the
instructions must only be performed by qualified personnel.
The device must be deenergised before any maintenance, cleaning and/or repair work.
15.1 General maintenance
Regularly check the myDatalogEASY IoTmini for mechanical damage.
Check all of the connections for leaks or corrosion on a regular basis.
l Check all of the cables for mechanical damage at regular intervals.
l Clean the myDatalogEASY IoTmini with a soft, moist cloth. Use a mild cleaning agent, if necessary.
l
l
15.2 Replacing the power supply unit
Important note: A dry location must be used to replace the power supply unit. If this is not possible,
protect the opened device against penetrating moisture using suitable means.
Opening the myDatalogEASY IoTmini
1 Delta PT M3.5x25 Torx 15
3 Housing cover
2 Power supply unit
4 Strap to remove the power supply unit
1. Ensure that all of the relevant data was transferred to the myDatanet server. If necessary, initiate a
transmission. To do so, execute the operations provided in the Device Logic and then check again that
all of the relevant data has been transferred.
Rev. 01
189
2. If you are using an external supply or charging voltage, disconnect this from the device before opening
the housing cover.
3. Remove the four screws that secure the housing cover. Now open the myDatalogEASY IoTmini .
4. Remove the power supply unit from the myDatalogEASY IoTmini and replace the existing power
supply unit with a new one. Use the strap provided to remove the power supply unit.
Note: Ensure that power supply units, especially ones with integrated energy store
(rechargeable battery or battery), are disposed of in line with environmental requirements.
Power supply units with depleted rechargeable battery or battery can be returned to the
manufacturer or handed in at suitable collection points.
Removing the power supply unit
1 Power supply unit
2 myDatalogEASY IoTmini base unit
The following step is not mandatory.
5. Check whether the connection to the myDatanet functions correctly (see "Testing communication with
the device" on page 69).
6. Close the housing cover. The best option is to tighten the four screws crosswise (torque: 0,5Nm; At the
first screw 0,7Nm because the threads have to be shaped into the base part first.) so that the housing
cover is positioned evenly.
Important note: Ensure that the seals are clean and intact before closing the housing cover.
Remove any impurities and/or dirt. The manufacturer shall not be liable for any damage to the
device caused by leaky or faulty seals.
190
Rev. 01
Chapter 15 Maintenance
7. Check that the housing cover is positioned correctly on all sides and that no foreign materials have
been trapped between the housing and housing cover.
Important note: The manufacturer is not liable for any damage that is caused by housing
covers that are not closed correctly.
The following step is only necessary if you are using an external supply or charging voltage.
8. Now switch on the external supply or charging voltage.
Note: If you are using a power supply unit without an integrated energy store, the external supply or
charging voltage must be switched on before the optional step during which the connection to the server
is tested.
15.2.1 Charging the power supply unit
All power supply units with an integrated and rechargeable energy store are delivered with a maximum
charge of 30% in accordance with applicable transport regulations. If you use an external charging voltage
(V IN) during operation, the power supply unit is constantly charged by the charge controller integrated in the
myDatalogEASY IoTmini .
If no external charging voltage (V IN) is available during operation, the power supply unit must be fully
charged before initial use.
For instructions on removing the rechargeable battery, see "Replacing the power supply unit" on page 189.
Important note: Only use the PSU Charger (300697) to charge the power supply units. The
charger specifications must be observed. The use of other chargers can destroy the power supply
unit, for example, causing the cells to leak or an explosion, etc.
Rev. 01
191
Charger with power supply unit
1 Plug-in power supply (included in the scope of
delivery of 300697)
4 PSU Charger (300697)
2 Button (reserved for extension)
5 Status LED of the PSU Charger
3 Power supply unit e.g. PSU413D+ AP (300524)
Possible states of the status LED:
off: no PSU inserted
Flashing green: PSU is being charged
Green: Charging completed
Flashing red 1x every 5 seconds: PSU does not
contain a rechargeable energy store
Flashing red 2x every 5 seconds: PSU damaged
Flashing red 3x every 5 seconds: Supply voltage
of the charger is too low
The charging process starts as soon as the power supply unit is inserted in the charger. If the status LED on
the charger flashes red once every 5 seconds, the power supply unit inserted in the charger does not contain
a rechargeable energy store. If the status LED flashes red three times every 5 seconds, the supply voltage of
the charger is too low. In this case, check the cable connection between the plug-in power supply and the
PSU Charger and check whether the plug-in power supply is correctly connected to an electric socket. If the
status LED flashes green, a normal charging process is in progress. The charging process is complete when
the status LED turns green.
192
Rev. 01
Chapter 15 Maintenance
If the status LED flashes red twice every 5 seconds, the power supply unit is faulty. Possible reasons for this
include a broken cable, short circuit or defective cells. In this case, the used power supply unit must be
replaced with a new one.
Note: Rechargeable batteries are wear parts that lose capacity over time. The capacity is also reduced at high
or low ambient temperatures and under intensive use.
Note: Ensure that power supply units, especially ones with integrated energy store (rechargeable
battery or battery), are disposed of in line with environmental requirements. Power supply units with
depleted rechargeable battery or battery can be returned to the manufacturer or handed in at suitable
collection points.
15.3 Power supply units with integrated energy store
While power supply units with integrated batteries (e.g. PSU713 BP ) are intended for single use and must be
disposed of accordingly after depletion, power supply units with integrated rechargeable batteries (e.g.
PSU413D+ AP ) can be recharged and used again and again. However, the service life of rechargeable
batteries is not indefinite. In addition to regular servicing and maintenance, its service life is also dependent on
the frequency of use and the operating and storage conditions.
Rev. 01
193
Chapter 16 Removal/disposal
Chapter 16 Removal/disposal
Incorrect disposal can cause environmental hazards.
Dispose of the device components and packaging material in accordance with the locally valid environmental
regulations for electronic products.
1. Disconnect any charging voltage that has been used.
2. Remove the power supply unit with the integrated energy storage (rechargeable or non-rechargeable
battery) and dispose of it separately.
3. Disconnect any connected cables using a suitable tool.
Logo of the EU WEEE Directive
This symbol indicates that the requirements of Directive 2012/19/EU regarding the scrap disposal
of waste from electric and electronic equipment must be observed. Microtronics Engineering
GmbHsupports and promotes recycling and environmentally friendly, separate collection/disposal
of waste from electric and electronic equipment in order to protect the environment and human
health. Observe the local laws and regulations on disposal of electronic waste at all times.
Microtronics Engineering GmbHreleases goods brought onto the market in Austria from the
obligations via ERA, which means that collection points that cooperate with ERA Elektro
Recycling Austria GmbH (https://www.era-gmbh.at/) can be used for disposal in Austria.
The device contains a lithium button cell that has been soldered on. It must be
removed before disposal or the disposal service must be informed that batteries are
still located in the device.
Rev. 01
195
Chapter 17 Troubleshooting and repair
Chapter 17 Troubleshooting and repair
17.1 General problems
Problem
Device does not
respond.
Communication
problems
Not all or no data is
available on the server.
Data at universal input
is not plausible.
The measurement
values of the external
temperature sensor
are not plausible.
The data of the RS485
interface is not
plausible.
Rev. 01
Cause/solution
l Check the cable connections (see "Connecting the sensors, actuators and
power supply" on page 50)
l The capacity of the energy store in the power supply unit is depleted.
Load the device log from the myDatalogEASY IoTmini using the
DeviceConfig (see "myDatanetDeviceConfig Manual " 805004). A list of all
the possible error codes is included in the chapter "Log entries and error
codes" (see "Log entries and error codes" on page 199).
l The capacity of the energy store in the power supply unit is virtually depleted.
l
The connection was aborted during the transmission, which is indicated by a
time-out entry in the connection list (see "myDatanet Server Manual "
805002). Solution: Initiate a transmission or wait for the next cyclical transfer.
l The Data Descriptor was not configured correctly (see "Data Descriptor " on
page 185).
l The assignment of the device and site is not correct (see "Site" on page 72).
l
Check the cable connections (see "Connecting the sensors, actuators and
power supply" on page 50)
l Check whether the output signal from the sensor that you are using is
compatible with the electrical characteristics of the universal inputs (see
"Technical details about the universal inputs" on page 55).
l Check whether the universal input configuration matches the sensor output
signal (see "UI_Init()").
l Check the filter settings of the universal input (see "UI_Init()")).
l The Data Descriptor was not configured correctly (see "Data Descriptor " on
page 185).
l
The chargeable feature "Activation code temperature input(300542)" has not
been released.
l Check the cable connections (see "Connecting the sensors, actuators and
power supply" on page 50)
l
The chargeable feature "Activation code RS485 (300540)" has not been
released.
l Check the cable connections (see "Connecting the sensors, actuators and
power supply" on page 50)
l Check whether the sensor that you are using is compatible with the electrical
characteristics of the interface (see "Technical details about the RS485
interface" on page 56).
l Check whether the interface configuration matches the sensor output signal
(see "RS485_Init()").
l Check the settings of the load resistance (see "RS485_Init()").
l
197
Problem
The data of the RS232
interface is not
plausible.
Isolated switch contact
is not working.
The Device Logic is not
being executed
correctly.
198
Cause/solution
l The chargeable feature "Activation code RS232 (300541)" has not been
released.
l Check the cable connections (see "Connecting the sensors, actuators and
power supply" on page 50)
l Check whether the sensor that you are using is compatible with the electrical
characteristics of the interface (see "Technical details about the RS232
interface" on page 57).
l Check whether the interface configuration matches the sensor output signal
(see "RS232_Init()").
l
Disruption to the voltage that is conducted via the relays
Check that the correct Device Logic type was selected during the
configuration of the control (see "Control" on page 73).
l Load the device log from the myDatalogEASY IoTmini using the
DeviceConfig (see "myDatanetDeviceConfig Manual " 805004). A list of all
the possible Device Logic error codes is included in the chapter "Pawn script
error codes" (see "Device Logic error codes" on page 161).
l The previous Device Logic has been replaced with that of the newly assigned
site/application due to a context change (assignment of a different
site/application).
l By assigning a new or different site/application, the Device Logic installed via
the USB has been replaced with that of the newly assigned site/application.
l
Rev. 01
Chapter 17 Troubleshooting and repair
17.2 Log entries and error codes
Log entry
Code
Plain text
1000 POWER ON
Parameter
Code
Plain text
0
---
Restart following a power failure
4
---
Watchdog reset (e.g. because of an exception)
6
---
Reset was initiated by the device itself (e.g. in
event of firmware update)
##
--
Restart for another reason. There may be a
hardware problem if the "POWER ON" log entry
with a parameter code that is not equal to 0 or 6
is contained in the device log several times.
Contact the manufacturer in this case (see
"Contact information" on page 209).
1030 UV LOCKOUT
---
---
The device switches to energy saving mode and
terminates all of the operations as the
rechargeable battery or battery voltage is too
low. Only the charge controller, if present,
remains active.
1031 UV RECOVER
---
---
The rechargeable battery or battery voltage once
again suffices to guarantee reliable operation.
This is either achieved by replacing the
rechargeable battery or battery pack or by
ensuring that the charge controller has charged
the battery sufficiently. The device resumes
normal operation in accordance with the
configuration.
1034 CONTROLLER
UPDATE
##
---
Controller firmware update was completed
successfully
Description
This entry is always duplicated in the device log.
In the first entry, the parameter specifies the
major version number (e.g. 3 for 03v011), while
in the second entry it specifies the minor version
number (e.g. 11 for 03v011).
1035 EXCEPTION
Rev. 01
##
---
An internal system error was detected that
caused the device to restart. The parameter
specifies the type of system error. Contact the
manufacturer if the device log contains this error
with the same parameter code several times
(see "Contact information" on page 209).
199
Log entry
Code
Plain text
1161 LOG
REFORMATFILE
Parameter
Code
Plain text
##
---
1192 FUTURE
TIMESTAMP
##
---
Description
Error in file system has been resolved. This can
result in data being lost (data and/or log entries).
The parameter contains more information on the
problem. Contact the manufacturer if the device
log contains this error with the same parameter
code several times (see "Contact information" on
page 209).
Internal error
Contact the manufacturer if the device log
includes this error several times (see "Contact
information" on page 209).
1281 ZLIB
##
STREAMPROCESS
ERR
---
1282 ZLIB
STREAMFINISH
ERR
---
##
Internal error
Contact the manufacturer if the device log
includes this error several times (see "Contact
information" on page 209).
Internal error
Contact the manufacturer if the device log
includes this error several times (see "Contact
information" on page 209).
1300 USB CONNECTED ---
---
USB connection to a PC established
1310 USB
DISCONNECTED
---
---
USB connection was terminated
2000 MODULE ERR
##
---
Area for customer-specific critical error codes,
that can be written in the device log by means of
the "rM2M_WriteLog()" pawn script function
##
---
Area for customer-specific non-critical error
codes, that can be written in the device log by
means of the "rM2M_WriteLog()" pawn script
function
##
---
Area for customer-specific information about the
current operating state, that can be written in the
device log by means of the "rM2M_WriteLog()"
pawn script function
##
---
Area for customer-specific debug information,
that can be written in the device log by means of
the "rM2M_WriteLog()" pawn script function
##
--
Error codes of the script execution (see "Device
Logic error codes" on page 161).
2199
2200 MODULE
WARNING
2399
2400 MODULE INFO
2599
2600 MODULE DEBUG
2799
3000 SCRIPT ERROR
3099
200
Rev. 01
Chapter 17 Troubleshooting and repair
17.3 Evaluating the device log
17.3.1 Evaluating the device log on the myDatanet server
The last 300 log entries on the myDatanet server can be called up via the button shown below that is located
in the measurement device list. As the log entries are sent to the server in the transmission cycle in the same
way as the measurement data, only the log entries up to the last server connection are available.
The manual for the server ("myDatanet Server Manual " 805002) includes a detailed description of the
evaluation of the device log on the myDatanet server.
17.3.2 Evaluating the device log using DeviceConfig
The DeviceConfig program can be used to read all of the stored log entries, including those that have not yet
been transferred to the myDatanet server, directly from the myDatalogEASY IoTmini via the USB interface.
A more detailed description about the evaluation of the device log using DeviceConfig is included in the user
manual for the DeviceConfig ("myDatanetDeviceConfig Manual " 805004).
Rev. 01
201
Chapter 18 Spare parts and accessories
Chapter 18 Spare parts and accessories
18.1 Chargeable features
Description
Order option (feature is activated by the manufacturer prior to delivery)
Quantity
Order number
Feature activation RS485
1
300730
Feature activation RS232
1
300731
Feature activation temperature input
1
300732
Feature activation LoRa
1
300971
Feature activationg BLE
1
300972
Activation code RS485
1
300540
Activation code RS232
1
300541
Activation code temperature input
1
300542
Activation code BLE
1
300968
Activation code (for later activation by the customer)
18.2 Assembly sets
Description
Universal bracket for housing myDatanet 86x126
Quantity
Order no.
1
206.640
DIN rail mounting set for myDatanet housing 86x126
1
206.634
Pipe mounting kit for myDatanet housing 86x126
1
206.660
18.3 Antennas
Description
Antenna LoRa FME -F
Rev. 01
Quantity
Order no.
1
301004
203
18.4 Power supply units
Description
Quantity
Order number
Battery packs
PSU713 BP (Li-SOCl2; 13Ah; -20...+50°C operating temperature)
1
300526
1
300524
PSU413D AP (Li-Ion ; 13,2Ah; -20...+60°C operating, 0...+40°C charging 1
temperature)
300525
Rechargeable battery packs
PSU413D+ AP (Li-Ion ; 13,6Ah; -20...+60°C operating, -20...+60°C
charging temperature)
Direct supply
PSU DC (-20...+60°C operating temperature)
1
300529
PSU AC : 230VAC power supply unit with Backup batterie (Li-Po ;
900mAh; -20...+60°C operating, 0...+40°C charging temperature)
1
300558
PSU DC+ (Li-Po ; 900mAh; -20...+60°C operating, 0...+40°C charging
temperature)
1
300798
18.5 Charging devices and power supply units
Description
Power supply 24V 1A
Quantity
Order number
1
213.814
Power supply 12V 1,25A
1
206.623
Power supply 24V 2,5A for top-hat rail mounting
1
206.667
Snap-on primary plug EU for chargers/power supplies
1
300027
Snap-on primary plug UK for chargers/power suppliest
1
300028
Snap-on primary plug US for chargers/power supplies
1
300029
Snap-on primary plug AUS for chargers/power supplies
1
300030
PSU Charger
1
300697
18.6 Other accessories
Description
myDatanet Tool Pen
Quantity
Order number
1
206.646
MDN Magnet
1
204
206.803
Rev. 01
Chapter 19 Document history
Chapter 19 Document history
Rev.
Date
01 28.08.2020 First version
Rev. 01
Changes
205
Chapter 20 Glossary
Chapter 20 Glossary
NaN value
The myDatanet uses special encoding to display different error statuses in the measurement values,
for example. By setting a measurement value to "NaN", it is clearly marked as invalid and is thus not
used for any further calculations. In the measurement value graphs, a measurement value that has
been set to "NaN" is indicated by an interruption in the graph. When downloading the data, a
measurement value set to "NaN" is indicated by an empty data field.
Rev. 01
207
Chapter 21 Contact information
Chapter 21 Contact information
Support & Service:
Microtronics Engineering GmbH
Hauptstrasse 7
3244 Ruprechtshofen
Austria, Europe
Tel. +43 (0)2756 7718023
[email protected]
www.microtronics.com
Microtronics Engineering GmbH
(Headquarters)
Hauptstrasse 7
3244 Ruprechtshofen
Austria, Europe
Tel. +43 (0)2756 77180
Fax. +43 (0)2756 7718033
[email protected]
www.microtronics.com
Rev. 01
209
Certified by TÜV AUSTRIA: EN ISO 9001:2015, EN ISO 14001:2015, EN ISO 50001:2011 for myDatanet | TÜV SÜD: ATEX Directive 2014/34/EU
© Microtronics Engineering GmbH. All rights reserved. Photos: Microtronics
Microtronics Engineering GmbH | www.microtronics.com
301115 | Rev.01
Hauptstrasse 7 | 3244 Ruprechtshofen | Austria | +43 2756 77180 | [email protected]
">