EmailRelay (Email Relay)

The EmailRelay function securely delivers an email message to one or more email addresses via a Campbell Scientific service, which is preferred over using a third party service such as Gmail or Yahoo. EmailRelay requires access to public internet and ClosedDNS Domain name server. A TCP/IP application protocol..

Syntax

Result = EmailRelay ( ToAddr, Subject, Message, ServerResponse, Attach [optional], NumRecs/TimeIntoInterval [optional], Interval [optional], IntervalUnits [optional], FileOption [optional], TimeOut [optional] )

Remarks

The EmailRelay function returns -1 if the relay server has received and sent the message, 0 if the connection to the server fails, -2 if execution of the function did not occur (for instance if the time or number of records interval are not met), or -3 if a connection was made but the relay server returns an error.

The email can be sent to one or more recipients and it can include attachments. The ServerResponse variable can be used to monitor the status of the email transmission. Note that with all communication functions, the transmission time will vary as a function of network bandwidth as well as datalogger type.

When multiple IP interfaces (for example, Ethernet port, CS I/O port, Wi-Fi, PPP) are active, the IPRoute() instruction is used to direct outgoing IP traffic.

If a connection to the email relay server is not made after 75 seconds, the instruction will time out. The optional TimeOut parameter can be used to change the default 75 second timeout. The datalogger waits for the instruction to return a result; thus, it can hold up the scan. However, the instruction can be placed in a slow sequence scan. In a slow sequence, EmailRelay will run in the background and will not hold up the main program waiting for the transaction to be completed. The ServerResponse variable can be used to monitor the status of email transmission.

The last several parameters are optional. The optional parameters can be used to send data from a data table directly to a server, without the datalogger first having to write the data to a file.

An ClosedIPTrace Function associated with IP data transmissions. IP trace information was originally accessed through the CRBasic instruction IPTrace() and stored in a string variable. Files Manager setting is now modified to allow for creation of a file on a datalogger memory drive, such as USR:, to store information in ring memory. code of 4800 in the datalogger's settings table can be used to analyze messages during an email send or receive to troubleshoot errors.

In addition to sending emails, EmailRelay can also send a text message (SMS) to a phone using an email-to-text message gateway, which is provided by most cellular providers. Text Message(SMS) via EmailRelay

Parameters

Result

The Result variable indicates if execution succeeded (-1), failed (0), did not occur when called (-2), or the server response contains an error message (-3). If using optional parameters to stream data from a data table/field, result is set to -2 if the instruction is called but does not execute because the number of records or time into interval conditions are not met.

ToAddr (Email "To" Address)

A string expression containing the recipient email address. Multiple recipients are specified as a comma separated list of addresses; for example “jack@email.com,jill@email.com”.

Type: String expression

Subject (Message Subject)

A string expression containing the text used in the Subject field of the message.

Type: String expression

Message (Email or Text Message)

A string expression containing the text used in the body of the email or text message. For messages being sent, variables can be included in the message using CRBasic's standard string syntax (for example, "The temperature is " + TempVar + " degrees C").

Type: String expression

ServerResponse (Server Response Messages)

A variable formatted as String that will be populated with mail server response messages during email transmission. Look at the content of this variable when monitoring the email send process or diagnosing problems.

Type: Variable formatted as a string

Optional PARAMETERS

Attach (File Attachment)

A string expression containing a local file name, comma separated list of local file names, data table name, or data table field name. Local files are generally created by TableFile or a Campbell Scientific camera. Multiple local file names can be specified as a comma separated list (for example, “SSDUSRCPU:file1.dat,SSDUSRCPU:image.jpg”). Make sure to include the file directory along with the file name. The only device choice for this datalogger is CPU.The directories in the datalogger are CPU (datalogger CPU), SSD (datalogger SSD drive), CRD (memory card), USR (user-defined drive), and USB (SC115).CS9 (SC115), and USB (External USB drive).

If streaming data directly from a data table or table field to an email attachment, this parameter should be a constant specifying the table name (for example, “TableOne”) or table field name (for example, “TableOne.BattV_Min”) that is used as the data source. Or, to stream all data tables, specify the optional data table parameters required for streaming and specify the data source as an empty string (“").

If an attachment is not required, specify this parameter as an empty string (“”) and do not specify the optional data table parameters.

Type: Variable formatted as a string

NumRecs/TimeIntoInterval (Time into Interval to Write the Number of Records)

Used only when streaming data directly from a data table or data table field.

For more details, see the Data Streaming document.

If Interval is greater than 0, the NumRecs/TimeIntoInterval parameter specifies the time into the interval at which previously unsent records should be written to file on the server.

If Interval is equal to 0, the NumRecs/TimeIntoInterval parameters specifies the number of previously unsent records that will be written to file on the server. If Interval is equal to 0, a negative NumRecs/TimeIntoInterval parameter will specify the number of records that will be written to file on the server each time the function is called.

Type: Constant, optional parameter

Interval

Used only when streaming data directly from a data table or data table field. If greater than 0, the Interval parameter determines the interval at which previously unsent data will be written to file. If equal to zero, the NumRecs parameter will control when data is written. A negative Interval will cause the datalogger to write the most recent records within this time interval each time the function is called.

NumRecs/
TimeIntoInterval
Interval Sent
0 0 All new (unsent) data in the data table is sent.
>=0 >0 Interval’s worth of previously unsent records. Only previously unsent data will be sent. If multiple intervals have passed between calls to this function,  multiple files will be written to the server and each file will contain interval’s worth of records.
>0 0 Number of previously unsent records. Only previously unsent data will be sent. If multiples of NumRecs have been recorded between calls to this function, multiple files will be written to the server and each file will contain NumRecs of records.
<0 0 Each time this function is called, the most recent records up to NumRecs will be sent.
0 <0 Each time this function is called, the most recent records within this time interval will be sent.

Type: Constant

Units

Used only when streaming data directly from a data table or data table field. It is used to specify the units on which the TimeIntoInterval and Interval parameters will be based. The options are microseconds, milliseconds, seconds, minutes, hours, or days.

Type: Constant

FileOption (File Format)

Used only when streaming data directly from a data table or data table field. It specifies the format of the file sent in the email. The file will automatically be appended with an incrementing file number and a “.dat” file extension. If 1000 is added to the format (for example, 1008), the datalogger will not automatically append the incrementing number or “.dat” extension to the file. Options 0, 8, 16, and 32 correspond to Campbell Scientific's defined formats for TOB1, TOA5, CSIXML, and CSIJSON, respectively.

Code Description
0 TOB1, Header, TimeStamp, Record#
1 TOB1, Header, TimeStamp
2 TOB1, Header, Record#
3 TOB1, Header
4 TOB1, TimeStamp, Record#
5 TOB1, TimeStamp
6 TOB1, Record#
7 TOB1
8 TOA5, Header, TimeStamp, Record#
9 TOA5, Header, TimeStamp
10 TOA5, Header, Record#
11 TOA5, Header
12 TOA5, TimeStamp, Record#
13 TOA5, TimeStamp
14 TOA5, Record#
15 TOA5
16 CSIXML, TimeStamp, Record#
17 CSIXML, TimeStamp
18 CSIXML, Record#
19 CSIXML
32 CSIJSON, TimeStamp, Record#
33 CSIJSON, TimeStamp
34 CSIJSON, Record#
35 CSIJSON

Type: Constant, optional parameter

TimeOut (Response Wait Time)

An optional parameter that specifies how long the datalogger will wait (specified in 0.01 seconds) before considering the attempt to connect to the server failed and returning the appropriate result code. The default TimeOut in the absence of this parameter is 7500 (i.e., 75 seconds). To specify a custom timeout without using the other optional parameters (that is, if not streaming data), use commas as placeholders for the unused parameters. For example, EmailRelay (“ToAddr, "Subject", "Message", "Attach", Result,,,,,,500). In this example, 6 commas precede 500, which sets the timeout to 5 seconds.

Type: Constant

The datalogger must have a working Ethernet, Wi-Fi, or PPP/cellular interface for email functions to work. A CR1000 datalogger is capable of email functionality, such as EmailRelay and EmailRecv, when it is capable of accessing a compatible email server via an internal or external Ethernet interface. When using an external serial device to access the email server, the external device must serve as a PPP host. The datalogger must obtain or be assigned a valid IP address, subnet mask, IP gateway, and in nearly all cases a DNS address. In order to resolve a qualified domain name, access to a domain name server is required.