Temperature Humidity Data Logger Commands API 2.4

User Manual: Temperature-Humidity-Data-Logger-Commands-API-2.4

Open the PDF directly: View PDF .
Page Count: 13

Download
Open PDF In Browser	View PDF

TEMPERATURE, HUMIDITY & DEW POINT
SENSOR AND LOGGER
API AND COMMAND BOOKLET

Version 2.4
September 2017

Temperature & Humidity Sensor API and Command Guide 2.4

BLUE MAESTRO’S STANDARD LICENSE AND DISCLAIMER
Copyright ©2017 Blue Maestro Limited. All Rights Reserved. The copyright in the software to which this document relates and in this
document belong exclusively to Blue Maestro Limited and no permission to use, copy, modify, and distribute this software or this documentation is permitted unless with the express prior written authorisation of Blue Maestro Limited. The license to use the software
to which this document relates is granted so long as such software resides in hardware provided by Blue Maestro Limited.
No claims, representations or warranties, whether expressed or implied, including but not limited to warranties of merchantability,
fitness for a particular purpose, of title, or of noninfringement of third party rights, are made by Blue Maestro as to the safety, reliability, durability or performance of Blue Maestro’s products. Blue Maestro is not responsible for any liabilities resulting from negligence,
misuse, modification, or alterations to the product by the user. Furthermore, Blue Maestro accepts no liability whatsoever for the
safety, reliability, durability or performance of any of its products. IN NO EVENT, REGARDLESS OF CAUSE, SHALL BLUE MAESTRO BE
LIABLE FOR ANY INDIRECT, SPECIAL, INCIDENTAL, PUNITIVE OR CONSEQUENTIAL DAMAGES OF ANY KIND, WHETHER ARISING UNDER BREACH OF CONTRACT, TORT (INCLUDING NEGLIGENCE), STRICT LIABILITY OR OTHERWISE, AND WHETHER BASED ON THIS
AGREEMENT OR OTHERWISE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
User assumes responsibility for correct operation of the product and any software associated with it. User assumes responsibility for
determining the suitability of the product to the user’s needs, for configuring and using the product to meet those needs, and for the
proper placement/location of the product in the environment it is being used. User assumes responsibility for verifying and interpreting results obtained from product use.
BLUE MAESTRO RESERVES THE RIGHT TO REVISE ITS STANDARD LICENSE AND DISCLAIMER WITHOUT NOTICE AT ANY TIME.

Temperature & Humidity Sensor API and Command Guide 2.4

Quick start
1.

Download the free iOS or Android App: Tempo Utility App

To get the links to the latest apps, please visit www.bluemaestro.com/support

Turn on

The soft touch colour rubber on top of the Device is a button. Depress gently to turn it on. The LED indicator will blink two times to confirm that it is on. Please note it should not be depressed with excessive
force, since this may damage the Device.
3.

Turn off

The Device can be turned by depressing the button and holding it down for a period of 5 seconds. It will
blink rapidly to indicate it is turned off.
4.

Entering Commands

Type *(star) followed by command name in the command line in the Command Console screen and press
send. The command name and examples are contained further on in this document.
For example type “*bur” into the command console and then send to see streaming temperature,
humidity and dew point up dated every 0.5 seconds.
You will now see temperature, humidity and dew point data shown in the app window.

PLEASE NOTE THIS API DOCUMENT IS FOR FIRMWARE VERSIONS 23 AND ABOVE

Temperature & Humidity Sensor API and Command Guide 2.4

Introduction
This document sets out the specifications, API and the commands of the Blue Maestro Temperature & Humidity Tempo Disc™ Bluetooth® Low Energy Sensor and Data Logger (the “Device”).
The Device uses the nRF52 Bluetooth Low Energy System on Chip from Nordic Semiconductor and a high
quality temperature and humidity sensor from Silicon Instruments. The Device utilises Bluetooth 4.1.
The Device adopts “ad-hoc” pairing where as much information is passed from Device to receiver (smartphone, iPad, Bluetooth enabled computer or Gateway) without pairing/bonding being required as possible. This is done through encoding information within the advertisement packets of the Device. Pairing is
reserved for the passing of commands from receiver to Device or for the extraction of data from the Device
where this cannot be achieved in the advertisement packet (such as logged data, for example).
There has been a great deal of flexibility introduced into the Device to allow settings to be changed. However care must be taken to ensure that settings are changed correctly. For example if certain undefined/
out of scope variables are input into settings the Device may not perform as desired and, possibly, lock-up
such it may only be able to be recovered by removing and then applying power.
There is a button and LED in the Device. The button is a software button that will cause the Device to consume an ever so small amount of current, even when turned off. To maximise battery life in transportation
and storage it is suggest that the battery is removed/not placed and is only inserted when the Device is to
be deployed.

Temperature & Humidity Sensor API and Command Guide 2.4

Specifications
The following is the specification for the Tempo Disc unit. For physical dimensions and form see further in
this document.
BLUETOOTH VERSION

SETTINGS FEATURES

4.1

The following represent some
of the settings that can be

BLUETOOTH SYSTEM ON
CHIP

Nordic Semiconductor nRF52832

MEMORY

64k RAM, 512k Flash

PROCESSOR

ARM Cortex M4 32-bit

BATTERY

CR2032, changeable

changed using the Command
Console:
Transmit Power, Advertising
Timeout, Name of Device, Rate
of Logging, Password Protect,
Reset Device, Device Information, Flight Safe Mode, Threshold Alarms for Temperature,

TEMPERATURE SENSOR
(SILICON LABS SI7020AGM)

Humidity or Dew Point (x2)

+/- 0.4 Degrees Celsius (max) with
an operating range of -20 to +75
Degrees Celsius

FREQUENCY OF LOGGING

Configurable from every 2
seconds to every 24 hours.
Default is hourly

HUMIDITY SENSOR
(SILICON LABS SI7020AGM)

+/- 4% Relative Humidity (max).

DEW POINT

Dew point is calculated from Tem-

ity and Dew Point. Log is on

perature and Humidity

a continuous rotation FIFO

Full range 0% - 100% Relative
Humidity

NUMBER OF LOGS

18,000 data points with 6,000
each of Temperature, Humid-

basis and stored in non-volatile
ANTENNA

memory

Johannson Technology
2450AT18D0100 omni-directionREAL TIME CLOCK

al chip antenna with matching

Device can be set with time
and date for accurate times-

tuning circuitry

tamping of logged data.
RANGE

up to 75 meters/245 feet line of
FLIGHT SAFE MDOE

sight

The Device can be put into airplane mode such that it logs

HARDWARE FEATURES

data but does not transmit ra-

Polycarbonate exterior with TPE

dio signals. When the button

soft touch button and LED indi-

is depressed, the Device will

cator
ENERGY CONSUMPTION OF
NRF52832 RX/TX

advertise for 5 minutes and it
can be taken out of airplane

nRF52832 Peak TX (0dBm) 5.3 mA;

mode.

running from Flash 58 µA for radio
transmissions

ESTIMATED BATTERY LIFE*

In excess of 18 months in Logging
Mode (continuous logging and

IP RATING

IP62

REGULATORY

EC/FC/RoHS compliant

COUNTRY OF MANUFACTURE

United Kingdom

Bluetooth transmission when
downloading log) and up to 9 - 12
months in Continuous Mode (continuous logging and Bluetooth
transmission).

* Battery life is estimated only can vary depending on device age, use case and
operating temperature. Battery life will be diminished when Disc is operated
continously at temperatures below 0°C.

Temperature & Humidity Sensor API and Command Guide 2.4

Advertisement Data Structure
The following represents the advertisement packet for the sensor. The first 30 bytes is the standard Advertisement payload and the second 30 bytes is the Scan Response payload. They are represented in bytes
with an offset beginning with Blue Maestro’s Bluetooth SIG company identifier 0x33 0x01. This is usually
located at the 16th byte in the full observed advertisement packet. The data structure is little endian.

Time interval for
logging uint16_t

Current Temp
Int16_t

Current Dew Point
Int16_6

0x33

0x01

0x17

0x64

0x00

Battery lvl in
% of voltage
uint8_t

Blue Maestro’s
SIG identifier
2 bytes

Stored log count
uint16_t

Current Humidity
Int16_t

Mode
Int8_t

Version No.
uint8_t

Breach Count
uint8_t

Length of Name

0x61

0x09

0x08

0xXX

0x00

Name Identifier
0x09

Name of Device
8 bytes

Reserved
4 bytes

Highest Temperature Recorded
int16_t

Lowest Temperature
Recorded
int16_t

Highest Temperature over last 24
hours - int16_t

Lowest Temperature
over last 24 hours
int16_t

0x33

0x01

0x74

0x53

0x61

0x66

0x65

0x00

Lowest Humidity
Recorded
int16_t

Highest Humidity
Recorded
int16_t

Blue Maestro’s
SIG identifier
2 bytes

Lowest Humidity
over last 24 hours int16_t

Highest Humidity
over last 24 hours int16_t

Reference Date
uint32_t

Average Humidity
over last 24 hours int16_t

0x61

0x69

0x74

0x53

0x61

0x66

0x65

0x00

Average Temperature over last 24
hours - int16_t

Global Identifier
uint8_t

Temperature & Humidity Sensor API and Command Guide 2.4

UART over BLE Communication

The following are a list of the command line syntax and field requirements to allow settings in the Device
to be changed.
The application includes one service: the Nordic UART Service. The 128-bit vendor-specific UUID of the Nordic UART Service is 6E400001-B5A3-F393-E0A9-E50E24DCCA9E (16-bit offset: 0x0001).
This service exposes two characteristics: one for receiving and one for transmitting (as seen from the nRF5
application).
TX Characteristic (UUID: 6E400002-B5A3-F393-E0A9-E50E24DCCA9E)
If the peer has enabled notifications for the TX Characteristic, the application can send data to the peer as
notifications. The application will transmit all data received over UART as notifications.
RX Characteristic (UUID: 6E400003-B5A3-F393-E0A9-E50E24DCCA9E)
The peer can send data to the device by writing to the RX Characteristic of the service. ATT Write Request
or ATT Write Command can be used. The received data is sent on the UART interface.
All commands and responses are ascii characters unless otherwise stated. The parameter fields of commands and responses are indicated by ‘X’. It is important that the correct number of fields in the parameters are complied with.
If a command is not recognised, the message “Unknown Command” will be transmitted. If a command is
recognised a “Command Recognised” will be transmitted. However even though the command is recognised the parameter may still be incorrect/out of bounds and the Device will not pass any indication.
Where a command is recognised the Device will disconnect and recommence advertising after processing the command. Where a password is entered incorrectly the Device will disconnect and recommence
advertising.

Transmission Strength [ *txpX]

This sets the transmission strength of the radio from a choice of three settings of -4dBm, 0dBm and
+4dBm. This can be useful for extending the battery life of the Device but has a negative impact on range.
The default setting is +4dBm.
Parameters:
000 sets to +4dBm
001 sets to 0dBm
003 sets to -4dBm

Temperature & Humidity Sensor API and Command Guide 2.4

Logging Interval [*lintX]

This sets the logging interval in seconds. The logging interval represents how frequently the sensor values
are stored in memory. The default is 3600 seconds which represents one hour. When changed, the current recorded data will be erased and logging will commence afresh. The minimum is 60 seconds and the
maximum is 43,200 seconds (or 12 hours).
Parameters: x in seconds (default is 3600 = 1 hourly logging interval)

Sensor Interval [*sintX]

This sets the sensor interval in seconds. The sensor interval represents how fequently the sensors take readings. The advertisement packets of the device are updated with the latest sensor readings. The defaut is 10
seconds. The minimum is 2 seconds and the maximum is 43,200 seconds (or 12 hours).
Parameters: x in seconds (default is 3600 = 1 hourly logging interval)

Password Protect [*pwdXXXX]

This locks the Device from receiving commands or having its log accessed. The Device is not password protected on shipping. Entering a password will lock the Device until the password is re-entered whereby the
Device will be unlocked until a password is again entered.
Parameters: 4 characters or numbers.

Change Name [*namXXXXXXXX]

This changes the Device name from its default. Please note that for some models of smartphone (both iOS
and Android) the name change will not necessarily be recognised until Bluetooth is turned off and back
on in the smartphone settings.
Parameters: 8 characters

Advertising Timeout [*atoXXX]

This sets the timeout parameters where advertising will cease after a button push. In all of these cases
advertising will commence in “fast mode” for 180 seconds and then in “slow mode” for a further number of
seconds as defined in this command. The default is 300 seconds or 5 minutes. It is important to note that
without advertising, the Device is not able to be connected to per Bluetooth 4.x protocols.
Parameters: XXX in seconds

Temperature & Humidity Sensor API and Command Guide 2.4

Information [*info]

This gives you a list of the current setting including the devices name , version number etc
Parameters: None

Telemetrics [*tell]

This gives you a list of the devices telemetrics including sensor frequency, log frequency, number of records, current temperature and the last 24hours metrics and other key data.
Parameters: None

10.

Units of Measure [*unitsf] [*unitsc]

This will convert temperature measurements into either fahrenheit or celsius.
Parameters: None

11.

Battery level [*batt]

This gives you the battery level as a percentage of voltage level. As the Device is powered by a CR2032 coin
cell, the voltage begins at 3.00 volts (100%). As the coin cell loses its charge, the voltage will drop. It is adviseable to change that the coin cell once the voltage drops to 2.1 volts (70%).

12.

Alarm one and two [*alrmUYZXXX]

There are two alarms which track how many times a sensor reading goes below or above a set threshold.
The occurrence of these alarms form part of the advertisement packet and when scanned by a smartphone or other receiving device can set off an “alarm”. The Device itself does not alarm.
The alarms can be set for temperature, humidity or dew point. Since there are two, you can set them for
any combination of these.
Parameters: U is the alarm number, either 1 or 2. So *alrm1t>25 sets alarm 1 for temperature over a threshold of 25 Celsius (if this is the units sets for the Device at the time)
Y is the sensor which the threshold applies, either t for temperature, h for humidity or d for dew point. For
example *alrm2h>50 sets alarm 2 for humidity over a threshold of 50% relative humidity.
XXX is the threshold to apply. It is in round numbers, so no decimal points can be specified. For example
*alrm2d<10 sets alarm 2 for dew point below 10 Celsius (if this is the units set for the Device at the time).

Temperature & Humidity Sensor API and Command Guide 2.4

13.

Clear alarms [*alrmclr]

This clears the settings for the alarms.
Parameters: None

14.

Alarm information [*alrmi]

This provides informations on the alarms, such as settings and how many times the sensor has breached
any thresholds.
Parameters: None

15.

Air mode on [*airon]

This sets the air mode on. This causes the Device to log information but not transmit, ideal for transportation by air. Once this command is entered, the Device will continue to transmit for a further 5 minutes
before ceasing. Depressing the Device’s button will cause the Device to transmit for a further 5 minutes.
Parameters: None

16.

Air mode off [*airoff]

This sets the air mode off and the Device will continue to continuously transmit as normal.
Parameters: None

17.

Download log in readable form [*loggert] [*loggerh] [*loggerd]

Either of these commands will download the relevant log for temperature, humidity or dew point for
analysis. Note using these commands does not store the data in the smartphone, for this use the specific
download button on the smartphone.

18.

Disable Button [*bd]

This command will prevent the button from turning the device on or off. It will still cause the LED to blink
and will cause the device to transmit if it is in airplane mode. This command works on a toggle basis, to
enable the button if it has been disabled pass the command [*bd] again.

19.

Calibrate Temperature [*ctXX]

This command will apply an offset to temperature readings to the value of XX. This needs to be integers
(no decimal points) and can be negative. This value needs to conform to the units of measure currently
selected for the device.
Parameters: Integer (can be negative)
10

Temperature & Humidity Sensor API and Command Guide 2.4

20.

Calibrate Humidity [*chXX]

This command will apply an offset to humidity readings to the value of XX. This needs to be integers (no
decimal points) and can be negative.
Parameters: Integer (can be negative)

21.

Reference Date & Time [*dXXXXXXXXXX]

This command sets the reference date and time for timestamping the logs. This date and time should
represent when the device was first activated since the device immediately records a log. The reference
date and time can be entered at any time and can be changed subsequently.
The format is a 10 digit number representing Year, Month, Day, Hour, Minute. No seconds are referenced.
For example 11:05pm 23 March 2017 would be represented as 1703232305. To set the date and time to
this the command would be *d1703232305. This value is part of the advertisement packet from the device.
Parameters: 10 digit number represeting xx[year]xx[month]xx[day]xx[hour]xx[minute].

22.

Global Identifier [*idX]

This provides a uint8_t number (0-255) that will be advertised in the Devices advertising packets for identification, classification or grouping purposes. This can be useful in scanning for Devices where a filter can
be applied based on the global identifier so that only certain devices are picked up in the app.
Parameters: Integer (can be negative)

23.

Clear Memory [*clr]

This command will erase the stored logs in the device. However it does not affect the logging interval,
name, global identifier, reference date or the like.

24.

Reset to Factory Settings [*rboot]

This command will perform a full reboot of the device and will clear all memory and settings.

Temperature & Humidity Sensor API and Command Guide 2.4

INTENTIONALLY BLANK

Temperature & Humidity Sensor API and Command Guide 2.4

Dimensions and form
The following represents the dimensions and form of the temperature & humidity sensor and logger.

9.5 mm
0.37 inch

33 mm
1.30 inch

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.4
Linearized                      : Yes
Language                        : en-GB
XMP Toolkit                     : Adobe XMP Core 5.6-c138 79.159824, 2016/09/14-01:09:01
Create Date                     : 2017:09:05 09:28:26+01:00
Metadata Date                   : 2017:09:05 09:28:28+01:00
Modify Date                     : 2017:09:05 09:28:28+01:00
Creator Tool                    : Adobe InDesign CC 2017 (Macintosh)
Instance ID                     : uuid:0ebcfeba-47f9-b048-8472-dd7d4eb3e5cd
Original Document ID            : xmp.did:c4691a7b-3568-4fc0-b7a8-9c9cb8c949ff
Document ID                     : xmp.id:8664be19-60bd-41db-85cb-964e48ea6707
Rendition Class                 : proof:pdf
Derived From Instance ID        : xmp.iid:44af5846-5deb-4a2d-969e-5f71b62c2a98
Derived From Document ID        : xmp.did:44af5846-5deb-4a2d-969e-5f71b62c2a98
Derived From Original Document ID: xmp.did:c4691a7b-3568-4fc0-b7a8-9c9cb8c949ff
Derived From Rendition Class    : default
History Action                  : converted
History Parameters              : from application/x-indesign to application/pdf
History Software Agent          : Adobe InDesign CC 2017 (Macintosh)
History Changed                 : /
History When                    : 2017:09:05 09:28:26+01:00
Format                          : application/pdf
Producer                        : Adobe PDF Library 15.0
Trapped                         : False
Page Count                      : 13
Creator                         : Adobe InDesign CC 2017 (Macintosh)

EXIF Metadata provided by EXIF.tools

Temperature Humidity Data Logger Commands API 2.4

Navigation menu

Versions of this User Manual:

Views

Navigation