AutoSens Macro Programs

The AutoSens tag read process is controlled by the AutoSens Macro Program. AutoSens programs consist of a series of lines that control the initialization and subsequent control of the reader when AutoSens is running. The following sections detail the macros that can be set up with examples of how they might be used. If you more or less know what your application needs to do for timing and data formatting, you can skip to Appendix B. Examples and find the case closest to your requirements. After you figure out which one works best, you can then look at the details in the sections immediately below to tweak the settings.

Syntax

AutoSens macro programs consist of a series of macros terminated by semicolons (;).

A macro consists of a series of letters or numbers separated by commas. There are 6 fields in a macro. The first field is the primary command such as i for initialization, r for read, and so on. The second field is a subcommand and typically specifies a variation on what that command does. The other 4 fields provide various parameters for detailed control of the macro. Any numeric field must be specified as an integer value. Values with decimal points will be rejected by the macro program validation process.

Note that when you enter a macro program, if the last fields in the macro are optional, they can be eliminated and the macro scanner will fill these options in as zeros. When the macro program is correctly parsed and reflected back to the ProSens Console, you will see these fields filled out as a series of 0's.

Initialization

There are two macros that fall under the initialization category. These should go into the macro program as the first line or two and preceed any commands not in this category.

i, m, 0;

The first line of every AutoSens program should be: "i, m, 0;" or, when filled out by the parser, "i, m, 0, 0, 0, 0;". This macro is an initialization macro, hence the "i" as the first field. The "m" in the second slot indicates that we are setting the reader mode with the 0 in the third slot indicating that we are setting it to mode 0. Mode 0 indicates that AutoSens is to use the saved RFID configuration when it runs. Currently, mode 0 is the only mode we support, but in the future, we will support other modes (fast read, sensitive read, etc.) to make the basic configuration easier to set up with minimal need to use the ProSens Console for those purposes.
i, l, c; or i, l, r, 0, rssi_threshold;

This inialization macro controls what is done with the internal tag information that is stored during the tag read process and before the data is reported to the AutoSens server.

The "i, l, c;" variant indicates that the number times the tag was seen on each antenna during a read cycle is to be stored in the internal tag list. If you have set your reader up to read on all 4 antennas, then the output data will include 4 numeric values one, for each of the antennas. If no tags are seen when an antenna is being read on, or an antenna is not included in the read sequence, the count for that antenna will be returned as 0.

The "i, l, r, 0, rssi_threshold;" variant of this initialization macro specifies that the maximum return signal strength indicator (RSSI) will be reported for each tag as read on each antenna. Just as above, if readings are made on all antennas, 4 values will be reported and if a tag is not seen on a given antenna or that antenna is not in the sequence, the RSSI slot for that tag will be reported as 0.0.

Note that you can use the rssi_threshold field to filter out weak tags. You should substitute a negative numeric value (in dB) to specify the weakest RSSI that you want to include in your data. You might use this if you have multiple read zones and want to reduce reading tags that are farther away and consequently have weaker signals. Note that these number are negative, so to specify this threshold you would need to specify something like -50.0 (i, l, r, 0, -50.0;) Note that if you want RSSI values reported, but you want every possible read, you should specify -100.0 for the rssi_threshold. (Once you are below about -80.0, the reader is very unlikely to read the tag.)

One last note here. The "i,l,c" macro and the "i,l,r" macro should not be specified together. If you do specify both, the one later in the macro program will override any that appear earlier. Due to memory limitations in the reader we only store counts OR RSSIs in the internal tag list rather than both.

Read Options

There are a number options for how the read process is timed and whether the data is saved in a list or streamed out. The read macros are split into 2 sections. The first 3 fields specify whether tag info is saved in an internal tag list for periodic reporting, or are streamed out as they are read. The last 3 fields specify how long read cycles last before the read process is stopped and data is sent to the server.

r, b, 0, ...; or r, l, 0, ...;

This part of the macro specifies whether data is streamed out or saved to a list during the actual tag inventory process.

The "r, b, 0, ...;" variant is used when data is to be streamed to the server. In general, when using AutoSens, you will be using the "r, l, ...;" variant rather than this one primarily because this one currently has very specialized uses. When reading tags using the ProSens Console (Read Tags tab) The AutoSens is being used to control the reads. The macro program that is being used to do that is "i,m,0;r,b,0;". This is the primary default setup for the reader when not using AutoSens.

The other specialized application for this macro is on the Extreme readers. In this case, you can specify the read option as "r, b, 0, timing_info;" where the data is effectively streamed to a server, but you can specify timing information over which the data is aggregated. This will be discussed in the timing section below, but generally, the timing interval is set to a very short period of time (e.g., 15 ms) so that very few reads are combined in this timing interval. This version of the macro has been used for tracking tagged items moving relatively quickly through the read field. Also, note that there is no clocked version of this macro available.

There are 2 things to note about this mode:
1. A special heartbeat (HB) record is reported periodically to let the server know that the reader is actively running the tag inventory process.
2. HTTP data delivery and JSON formatting of the output data is currently not supported for this mode.
The "r, l, 0, ...;" variant is the most typical setup for the AutoSens read process. This version reads tag information into an internal tag list and accumulates the number of tags read on each antenna over the timing interval or the maximum RSSI value for a tag at each antenna. This macro requires timing interval information as will be discussed next.
r, ..., c, 0, clock_interval; or r, ..., i, read_interval, 0;

The last three fields specify the interval during which the reads are performed and the data is aggregated. After reading for that period of time, the read process is temporarily suspended while tag reads are delivered to the server. Once tag information has been delivered to the server, the AutoSens program resumes, typically cycling back to the read macro.

The "..., c, 0, clock_interval;" variant specifies that a new read cycle will begin as closely as possible to regular clock intervals. The clock_interval parameter is in seconds. So a read macro such as "r, l, 0, c, 0, 20" specifies that the reader will start a new read cycle every 20 seconds. Because the number of tags read during a read cycle can vary, this can't be precise, but the reader firmware adapts to get this as close as possible.

The "..., i, read_interval, 0;" variant reads for the time interval specified by the read_interval parameter. This parameter is in milliseconds. An example of this would be "r, l, 0, i, 20000, 0;". Note that this will also read tags for 20 seconds much like the clocked timing. However, this read process does not attempt to stay synchronized to the clock resulting in some small drift in when the reads occur. Where the clocked read above will work to maintain 3 reads per minute, the interval timing may only accomplish the 3 reads in slightly longer than a minute.

Data Management

When data is saved to a list, it can then be delivered to the server with the data formatting specified in this section. There is also a command that controls how the data in the internal list is cleared.

n, t, 0; or n, j, 0;

This macro specifies the data notification formatting. This macro typically follows the read (r) macro and triggers AutoSens to send data saved in the internal tag list during the read process to the configured server.

The "n, t, 0;" variant specifies that the data should be sent in comma separated text format. There are a couple of variations of this formatting based on other options. Please see Appendix A. Output Data Format for the details.

The "n, j, 0;" variant specifies that the data should be sent using JSON formatting. Again, see Appendix A. Output Data Format for the details.
l, c; or l, x, 0, 0, aging_interval;

The list (l) macro specifies what to do with the contents of the internal tag list when this macro is encountered. This would typically follow the notification (n) macro to determine how tags that have been read should be handled for the next read round.

The "l, c;" variant of this macro specifies that the entire contents of the tag list be cleared so that the next read cycle starts from an empty list.

The "l, x, 0, 0, aging_interval;" specifies that any tags that have not been seen in the time interval specified by that aging_interval field should be removed from the list. This provides a method to determine whether tags have potentially left the field on not. Note that the aging_interval is specified in seconds.

Miscellaneous Macros

p, 0, 0, 0, pause_interval;

This macro introduces a delay in the program when no reads or data maangement activities occur. This can be used for cases where the reader simply needs to wake up every so often and read for a period of time, report the tags seen, then go back to sleep for the pause_interval. The pause_interval is in milliseconds, so a 60 minute sleep period would need to specify a pause_interval of 3600000 ms (60 minutes * 60 sec/min * 1000 ms/sec). This value is stored as a 32 bit unsigned integer so the maximum pause_interval is 2^32 which is around 1193 hours. If you wanted to wake up and take an inventory once a day, this would be "p, 0, 0, 0, 86400000;".

Appendix A. Output Data Format

The following document the formats for the tag data reports. Generally, data is reported periodically with a reader section identifying the reader and when the report was sent along with a list of EPCs and information about how often and when the tags were seen. Note that if no tags were seen, the list will be empty.

Text Format

For all SensThys readers that are using the "r, l, 0,...;" variant of the read process, i.e., saving to the internal tag list rather than streaming, the data records are formatted as follows. The fields in <>'s will contain the actual data from the tag inventory process formatted as follows:

<MAC_ADDRESS> -- XX:XX:XX:XX:XX:XX where the X's are the hexadecimal values of each octet of the Ethernet interface of the reader.
<ANTENNA_SEQUENCE> -- The antenna sequence will be a 1 to 8 character string indicating the antenna ids as they appear in the antenna sequence. For example, if the reader is set up to read on the internal antenna, the sequence will simply be 0. If the read sequence is 0, 2, 0, 3 (reading on antenna 0 twice during the sequence) the <ANTENNA_SEQUENCE> field will be 0203.
<REPORT_TIMESTAMP>, <FIRST_SEEN_TIMESTAMP>, <LAST_SEEN_TIMESTAMP> -- The timestamp fields are all reported in the format "yy-mm-ddTHH:MM:SS" for Enterprise and Core readers and as "yyyy-mm-dd HH:MM:SS.fff" for streaming mode on Extreme readers, where every subfield is 2 digits in length and is preceeded by a 0 when the value is less than 10. The hours field uses a 24 hour clock.
-- This field is formatted as a hexadecimal string where each pair of hexadecimal digits provides the value of a byte from the EPC stored on the tag.

Text Formatting for Reporting Tag Counts

TAG_REPORT, <MAC_ADDRESS>, <ANTENNA_SEQUENCE>, <REPORT_TIMESTAMP>
<MAC_ADDRESS>, <EPC1>, 22, 0, 3, 0, <FIRST_SEEN_TIMESTAMP>, <LAST_SEEN_TIMESTAMP>
<MAC_ADDRESS>, <EPC2>, 10, 0, 15, 0, <FIRST_SEEN_TIMESTAMP>, <LAST_SEEN_TIMESTAMP>
...
\0

The count fields show the number of times a particular tag was seen on each physical antenna. In this example, there were 22 reads on the internal antenna and 3 on antenna 2. Note that if no tags were seen, or the antenna is not in the read sequence, a count of 0 will be reported.

Note that the tag stream will be terminated with a single byte data record containing the the value \0 (0x00). Also, the reader will close the connection to the server.

Text Formatting for Reporting Max RSSIs

TAG_REPORT, <MAC_ADDRESS>, <ANTENNA_SEQUENCE>, <REPORT_TIMESTAMP>
<MAC_ADDRESS>, <EPC1>, -50.0, 0.0, -65.0, 0.0, <FIRST_SEEN_TIMESTAMP>, <LAST_SEEN_TIMESTAMP>
<MAC_ADDRESS>, <EPC2>, -58.0, 0.0, -72.0, 0.0, <FIRST_SEEN_TIMESTAMP>, <LAST_SEEN_TIMESTAMP>
...
\0

The RSSI fields show the maximum RSSI for that tag as seen on each physical antenna. In this example, the maximum RSSI read on the internal antenna was -50.0 dBm and -65.0 on antenna 2. Note that if no tags were seen, or the antenna is not in the read sequence, the maximum RSSI value will be reported as 0.0.

Note that the tag stream will be terminated with a single byte data record containing the the value \0 (0x00). Also, the reader will close the connection to the server.

Text Formatting When Using Streaming Mode on Extreme Readers

The "r, b, 0, ...;" read mode on Extreme has a special minimal data format that currently is not supported on the Enterprise or Core readers. The output for this mode consists of a continuous stream of "TD" (Tag Data) records with "HB" (HeartBeat) records interspersed. The heartbeat records are sent out at the configured heartbeat interval for the reader and serve as a means to allow the server software to detect possible disconnects or other causes of reader downtime.

The data stream is formatted as follows:

HB, <MAC_ADDRESS>, <HEARTBEAT_TIMESTAMP>
TD, <MAC_ADDRESS>, <ANTENNA_ID>, <EPC>, <LAST_SEEN_TIMESTAMP>
...

Note that the streaming mode reports EPCs on an antenna_id-by-antenna_id basis rather than compress the data stream into a single record for each EPC with counts or RSSIs shown as an array for each EPC. The <ANTENNA_ID> field reports the physical antenna number (0-3) for the reported data.

JSON Format

JSON Formatting for Reporting Tag Counts

{
    "tag_report": 
    {
        "mac_address": "<MAC_ADDRESS>",
        "antenna_sequence": "<ANTENNA_SEQUENCE>",
        "report_timestamp": "<REPORT_TIMESTAMP>"
    },
    "tags":
    [
        {
            "macaddr": "<MAC_ADDRESS>",
            "epc": "<EPC>",
            "counts": [22, 0, 3, 0],
            "first_seen": "<FIRST_SEEN_TIMESTAMP>",
            "last_seen": "<LAST_SEEN_TIMESTAMP>"
        },
        ...
    ]
}

The count fields show the number of times a particular tag was seen on each physical antenna. In this example, there were 22 reads on the internal antenna and 3 on antenna 1. Note that if no tags were seen, or the antenna is not in the read sequence, a count of 0 will be reported.

JSON Formatting for Reporting Max RSSIs

{
    "tag_report": 
    {
        "mac_address": "<MAC_ADDRESS>",
        "antenna_sequence": "<ANTENNA_SEQUENCE>",
        "report_timestamp": "<REPORT_TIMESTAMP>"
    },
    "tags":
    [
        {
            "macaddr": "<MAC_ADDRESS>",
            "epc": "<EPC>",
            "rssis": [-50.0, 0.0, -65.0, 0.0],
            "first_seen": "<FIRST_SEEN_TIMESTAMP>",
            "last_seen": "<LAST_SEEN_TIMESTAMP>"
        },
        ...
    ]
}

Appendix B. Examples

Example 1. Interval timing, JSON data delivery

The following AutoSens program reads tags for a 2 second interval, stops the inventory process to deliver tags to the server using JSON data formatting, then clears the list and repeats the process.

i, m, 0, 0, 0, 0;
i, l, c, 0, 0, 0;
r, l, 0, i, 2000, 0;
n, j, 0, 0, 0, 0;
l, c, 0, 0, 0, 0;

Line by line:

i, m, 0, 0, 0, 0;
-- Required initialization macro.
i, l, c, 0, 0, 0;
-- This initialization macro specifies that the number of times seen (count) on each antenna will be reported.
r, l, 0, i, 2000, 0;
-- This macro specifies that the tag data will be written to the internal tag list to be reported out when the "n" macro is encountered. It also specifies that the tag inventory will be run for 2 seconds (2000 ms)
n, j, 0, 0, 0, 0; -- This notification macro specifies that the data will be reported using JSON formatting.
l, c, 0, 0, 0, 0;
-- Once the data has been reported, this macro specifies that the list will be cleared for the next read cycle.

The following JSON data record is an example of the data that would be generated from this AutoSens program.

{
    "tag_report":
    {
        "mac_address":"04:91:62:1e:8f:dc",
        "antenna_sequence":"0",
        "report_timestamp":"19-01-07T00:12:27"
    },
    "tags":
    [ 
        {
            "macaddr":"04:91:62:1e:8f:dc",
            "epc":"1903130001000F0000010826",
            "counts":[   19,    0,    0,    0],
            "first_seen":"19-01-07T00:12:25",
            "last_seen":"19-01-07T00:12:27"
        },
        {
            "macaddr":"04:91:62:1e:8f:dc",
            "epc":"696EF85EBDCF5F07C75B0B86DF684E49",
            "counts":[    4,    0,    0,    0],
            "first_seen":"19-01-07T00:12:26",
            "last_seen":"19-01-07T00:12:27"
        },
        ...
    ]
}
...

Example 2. Clock timing, Text data delivery

In this example, the AutoSens tag read process uses 15 second clock intervals to time the read process. It reads to the internal tag list every 15 seconds, delivers data to the server in text format and expires tags from the tag list that have not been read for the last hour.

i, m, 0, 0, 0, 0;
i, l, r, 0, -60, 0;
r, l, 0, c, 0, 15;
n, t, 0, 0, 0, 0;
l, x, 0, 0, 3600, 0;

i, m, 0, 0, 0, 0;
-- Required initialization macro.
i, l, r, 0, -60, 0;
-- This initialization macro specifies that the number of times seen (count) on each antenna will be reported.
r, l, 0, c, 0, 15;
-- This macro specifies that the tag data will be written to the internal tag list to be reported out when the "n" macro is encountered. This macro also specifies that inventory should be run every 15 seconds based on clock time.
n, t, 0, 0, 0, 0; -- This notification macro specifies that the data will be reported using JSON formatting.
l, x, 0, 0, 3600, 0;
-- Once the data has been reported, this macro specifies that any items in the list that have not been seen in the last hour should be removed for the next read cycle.

The following shows an example of the output data that might be generated by this AutoSens program.

TAG_REPORT, 04:91:62:1e:8f:dc, 0, 19-01-04T23:29:35
04:91:62:1e:8f:dc, 1903130001000F0000010826, -59.1, 0.0, 0.0, 0.0, 19-01-04T23:29:20, 19-01-04T23:29:32
04:91:62:1e:8f:dc, 1903130001000F0000010827, -59.9, 0.0  0.0, 0.0, 19-01-04T23:29:29, 19-01-04T23:29:29
04:91:62:1e:8f:dc, E2004202B9F060150093DDBF, -54.8, 0.0, 0.0, 0.0, 19-01-04T23:29:20, 19-01-04T23:29:24
04:91:62:1e:8f:dc, E2004202B8E060150093DDAE, -57.0, 0.0, 0.0, 0.0, 19-01-04T23:29:20, 19-01-04T23:29:25
04:91:62:1e:8f:dc, E2004202BB0060150093DDD0, -58.3, 0.0, 0.0, 0.0, 19-01-04T23:29:20, 19-01-04T23:29:32
TAG_REPORT, 04:91:62:1e:8f:dc, 0, 19-01-04T23:29:50
04:91:62:1e:8f:dc, 1903130001000F0000010826, -59.1, 0.0, 0.0, 0.0, 19-01-04T23:29:35, 19-01-04T23:29:47
04:91:62:1e:8f:dc, E2004202B9F060150093DDBF, -55.8, 0.0, 0.0, 0.0, 19-01-04T23:29:35, 19-01-04T23:29:48
...

Example 3. Streaming data delivery on an Extreme

The macro program in this example only works on the Extreme reader. It simply streams tag data to the server aggregating data over 15 ms intervals.

i, m, 0, 0, 0, 0;
r, b, 0, i, 15, 0;

i, m, 0, 0, 0, 0; -- Required initialization macro.
r, b, 0, i, 15, 0;
-- This macro specifies that the tag data will be streamed (r, b) to the server with minimal aggregation (15 ms) of the data internal to the reader.

The following shows the output data from this AutoSens program. Note the HB record in the middle of the data stream.

TD,00:1f:7b:73:07:10,0,E282403D000208DB04762A25,2022-05-04 22:12:26.451
TD,00:1f:7b:73:07:10,0,E282403D000208DB04762A25,2022-05-04 22:12:26.525
TD,00:1f:7b:73:07:10,0,E282403D000208DB04762A25,2022-05-04 22:12:26.593
TD,00:1f:7b:73:07:10,0,E282403D000208DB04762A25,2022-05-04 22:12:26.697
HB,00:1f:7b:73:07:10,2022-05-04 22:12:26.769
TD,00:1f:7b:73:07:10,0,E282403D000208DB04762A25,2022-05-04 22:12:27.190
TD,00:1f:7b:73:07:10,0,E282403D000208DB04762A25,2022-05-04 22:12:27.252
TD,00:1f:7b:73:07:10,0,E282403D000208DB04762A25,2022-05-04 22:12:27.307
TD,00:1f:7b:73:07:10,0,E282403D000208DB04762A25,2022-05-04 22:12:27.382
...