APPNOTE: PMGateway SMS command set

Article ID: 150323sab
Last Reviewed: June 27 2018

See also:
APPNOTE: Installing PmScreen on an Android Device.
APPNOTE: PMGateway Setup Guide.

The information in this article applies to:

  • PMGateway version 3.0.24 and later when used to provide remote access to one of the Power Master Loggers
  • NOTE: PMGateway was previously called PmRemoteAgent in older releases.

Target Audience.

This article is aimed at:

Summary.

PMGateway is an application that provides timed remote download of recorded files and general control of a Power Master Logger. It runs on a phone or tablet running the Android operating system.

A feature of PMGateway is its ability to be controlled remotely by commands sent via SMS. PMGateway receives, interprets and performs the command requested, enabling the user to change PMGateway’s settings, or transmit the command to the logger via Bluetooth, Ethernet, or USB.

Before you start.

You will need all of the following:

1) An Android device to which you can send SMS messages.

    If using Bluetooth: device must be within 10m (Bluetooth maximum range) of the Power Master Logger that you are using to record data.
    If using USB: device must be within 5m of the Logger.
    If using Ethernet: location of the device is irrelevant as long as both the Android device and the logger are connected to the same network.

2) A copy of PMGateway installed on the Android device.

3) A Power Master PM1000, PM2000, PM3000 or PM7000 with a Bluetooth, USB or Ethernet interface.

4) A device from which to send SMS messages.

Command Format.

All commands have a common format and follow these conventions:

1) A command starts with the period / dot character “.”

2) A single command word immediately follows the period / dot character.

3) The parameters (if required) follow the command word and are space separated.

4) A parameter containing spaces must be enclosed in double quotes.

5) A final optional parameter determines where any response generated should be sent.

6) Commands are not case sensitive so .start .START and .stART are all considered the same.

Command quick reference.

Communications Setup and Registration Info

Command Parameter 1 Parameter 2 Parameter 3
.email <user>@<domain.com> [email | sms | none]
.response [email | sms | none]
.login [phone number] [email | sms | none]
.logout [phone number] [email | sms | none]
.numbers [email | sms | none]
.settings [email | sms | none]

Logger Setup and Configuration Management

Command Parameter 1 Parameter 2 Parameter 3
.scan [email | sms | none]
.logger <Logger Serial No.> [email | sms | none]
.config [email | sms | none]
.configupload http(s)://<domain>/<filename>.zip [email | sms | none]
.configlist [email | sms | none]
.configload <filename>.plc [email | sms | none]

Recording

Command Parameter 1 Parameter 2 Parameter 3
.start [email | sms | none]
.stop [email | sms | none]
.restart [email | sms | none]

Polling

Command Parameter 1 Parameter 2 Parameter 3
.pollinterval <minutes> [email | sms | none]
.pollstart [email | sms | none]
.pollstop [email | sms | none]

State Information

Command Parameter 1 Parameter 2 Parameter 3
.status [email | sms | none]
.values [email | sms | none]

Alerts 

Command Parameter 1 Parameter 2 Parameter 3
.alertenable [email | sms | none]
.alertdisable [email | sms | none]
.alertemail <user>@<domain.com> [email | sms | none]

Development

Command Parameter 1 Parameter 2 Parameter 3
.registers <location> <count> [email | sms | none]

Command descriptions.

Communications Setup and Registration Info

.email command

Specifies the email to send data and responses to.

Example: 

SMS Sent Action
.email john.doe@example.com Sets the email for results to: john.doe@example.com

.response command

Sets the default response method – this is how PMGateway will respond when a command is sent that does not have: <email>, <sms> or <none> appended.

NB: if <email>, <sms> or <none> are appended to any future command, the response will be sent by that method for that single instance of the command only, and will otherwise default back to the method that has been set when the .response command was last used.

Examples: 

SMS Sent Action
.response email SMS commands received from now on will by default respond over email, unless stated otherwise
.response none No response will be returned from SMS commands.

 

.login command

For security and data integrity reasons, PMGateway ignores messages received from a number/phone that is not authorised. The .login command adds a new number to a list of authorised numbers that will be able to control the app via SMS. This command only needs to be used once for each number/phone authorised to control PMGateway. There are two ways you can use this command to authorise a number:

1) When next to the device running PMGateway, ensure PMGateway is running in the foreground and send the .login command without any parameters from the device you wish to authorise. PMGateway presents a dialog on the screen requesting confirmation. Click Yes to add the number to the authorised number list.

2) When not near the device running PMGateway a number can be authorised, from a second previously authorised number, by sending the .login command followed by the number of the phone to be authorised.

Examples: 

SMS Sent Action
.login  012345678910  email Adds 012345678910 to the authorised numbers list and send response back over email.
.login Add this phones number to the authorised numbers list (local access to the device running PMGateway required to accept)

 

.logout command

Removes a number from the list of authorised numbers.

Example: 

SMS Sent Action
.logout 012345678910 Deletes 012345678910 from the list of authorised numbers (this can be sent from 012345678910 but would be the last command able to be accepted from that number)

.numbers command

Returns a list of authorised numbers.

Example: 

SMS Sent Action
.numbers email Sends list of registered numbers via email.


.settings command

Returns the current general settings for PMGateway.

Example: 

SMS Sent Action Example Response
.settings email Returns PMGateway settings poll.period=15
email.address=<user>@<domain.com>
email.interval=every hour
upload=email
PM7S0363.connection=bluetooth

 

Logger Setup and Configuration Management

NB: If using .ConfigUpload or .ConfigLoad commands with a configuration file with a symbol in it, be aware that PmGateway will not recognise the file unless the symbol is correct – in these cases, users may want to find other methods of loading/uploading files (such as using PmFile), or renaming the configuration file before attempting these commands.

.Scan Command

Performs a Bluetooth scan and reports any Loggers found.

Example: 

SMS Sent Action Example Response
.scan PMGateway will scan for nearby loggers (unless a poll is in progress) Bluetooth devices detected:
PM7000sn0501
PM7000sn1107
PM7000sn1065
PM7000sn0363
PM3000sn0850

 

.Logger Command

Select which Logger to use for further commands.

Example: 

SMS Sent Action
.logger PM7S0123  Selects PM7000 serial number 0123 for any subsequent commands.

 

.Config Command

Extracts the current configuration from the Logger and sends it to the registered email address.

Example: 

SMS Sent Action
.config Sends the current configuration from the selected Logger to the registered e-mail address

 

.ConfigUpload Command

Allows a configuration to be uploaded from a URL.
The URL must point to a zip file containing a single .plc file and must be accessible by the PMGateway device using http or https.
URLs containing spaces must be inside quotation marks.

Example: 

SMS Sent Action
.configupload “http://www.example.com/loggers/3p4wYconfig.zip” Downloads the zip file from the specified URL to the phone, unzip it and transfer the included .plc file to the Logger.

 

.ConfigList Command

Get a list of configs present in the Logger and send it to the registered email address.

Example: 

SMS Sent Action
.configlist Sends a list of configurations by email.

 

.ConfigLoad Command

Load a specified configuration into the Logger.

Example: 

SMS Sent Action
.configload “3p 4w Y Std PQ 8MB 400A 7day.plc” Loads the specified configuration into the Logger.

 

Recording

.start command

Starts the Logger recording (if the Logger is already recording this has no effect).

Examples: 

SMS Sent Action
.start email Starts the Logger recording, sending the result over email
.start sms Starts the Logger recording, sending the result back in an SMS

 

.Stop Command

Stops the Logger recording (if the Logger is not recording this has no effect).

Examples: 

SMS Sent Action
.stop email Stops the Logger recording, sending the result over email
.start sms  Stops the Logger recording, sending the result back in an SMS

 

.Restart Command

Stops and then starts the Logger recording. If the Logger is not recording, this will start the Logger recording.

Examples: 

SMS Sent Action
.restart email Stops the current recording and start the next session, sending the result over email
.restart sms Stops the current recording and start the next session, sending the result back in an SMS

Polling

.PollInterval command

Specifies the interval in minutes at which to poll the logger.

Example: 

SMS Sent Action
.pollinterval 15 Sets the poll interval to 15 minutes

.PollStart command

Starts PMGateway polling the Logger.

Example: 

SMS Sent Action
.pollstart First poll will occur on the next interval boundary

 

.PollStop Command

Stops PMGateway polling the Logger.

Example: 

SMS Sent Action
.pollstop Finishes any poll in progress then do no more polling

 

State Information

.Status Command

Reads the Loggers status and returns the results.

Example: 

SMS Sent Action Example Response
.status email Gets the Logger status, sending the result back in an email PM1S0651
Status: Recording
Battery Volts: 5.979 V
Ambient Temp: 32.8 deg
Firmware: 1.025
Free Memory: 89.3 %

 

.Values Command

Reads the Loggers channel values and returns the results.

Example: 

SMS Sent Action Example Response
.values email Gets the channel values, sending the result back in an email Channels:
01=230.8 Vac
02=  8.1 Aac
03=  2.0%
04=  2.2 Aac
05= 0.00 Pfs
06= 1.00 Flg
07= 0.37 Pst
08= 0.33 Plt
09= 0.49 Vac
10=50.05 Hz

 

Alerts

.AlertEnable Command

Some Loggers include an Alert flag which is checked when the Logger is polled. If enabled and the alert flag is set when a poll occurs an email is sent immediately, rather than waiting for the next email interval.

Example: 

SMS Sent Action
.alertenable Turns on alert emails.

 

.AlertDisable Command

Turns off alert emails. If supported the alert status is still checked and reported with the normal emails.

Example: 

SMS Sent Action
.alertdisable Turns off alert emails

 

 

.AlertEmail Command

Sets an email address to which to send alert e-mails – can be used to send alerts to a different email address to which all other responses are sent to.

Example: 

SMS Sent Action
.alertemail jane.doe@example.com Sets the email for alerts to: jane.doe@example.com

Development

.Registers Command

This command is reserved for development – not for use by end users.