Telegesis ETRX357-LR, ETRX357, ETRX3 Series, ETRX357-LRS, ETRX357HR Command Manual

Telegesis

TG-ETRXn-R309-AT-Commands

ETRX3 series

AT-Command Dictionary 3.09

ETRX3 Series ZigBee Module

AT-Command Dictionary

Firmware R309

EmberZNet 5.4.0 stack

R309 AT Commands

Table of Contents

1 INTRODUCTION ................................................................................................................. 4

1.1 The first step .................................................................................................................... 4

1.2 Module overview .............................................................................................................. 4

1.3 Document Overview ......................................................................................................... 4

1.4 Network topology ............................................................................................................. 5

1.5 The ADCs ........................................................................................................................ 5

1.6 RTC Related Commands ................................................................................................. 5

1.7 A Note on ZigBee® Compliance ....................................................................................... 5

1.8 Important notes ................................................................................................................ 6

1.8.1 Hardware compatibility ..................................................................................................... 6

1.8.2 Unexpected start-up in bootloader mode .......................................................................... 6

1.8.3 Compatibility with other devices ....................................................................................... 6

1.8.4 Persistence of network parameters .................................................................................. 6

2 AT STYLE COMMAND CONVENTIONS ............................................................................ 7

2.1 Parameters ...................................................................................................................... 8

2.2 Prompt Overview.............................................................................................................. 9

2.3 Device Overview ............................................................................................................ 11

2.3.1 ZigBee types .................................................................................................................. 11

2.3.2 Non-ZigBee types .......................................................................................................... 11

2.4 Addressing modes ......................................................................................................... 11

2.5 AT Command Overview ................................................................................................. 13

2.6 Module Control & Configuration Commands .................................................................. 15

2.7 Network Control & Configuration Commands ................................................................. 21

2.8 Messaging...................................................................................................................... 40

2.9 Binding Management (ETRX3 Series only) .................................................................... 58

2.10 Time-related commands ................................................................................................. 63

3 LIST OF ERROR CODES ................................................................................................. 65

4 S-REGISTERS .................................................................................................................. 67

4.1 Recovery of the Factory Default Settings ....................................................................... 69

4.2 S-Registers for Network Setup ....................................................................................... 70

4.3 S-Registers for Module Setup ........................................................................................ 75

4.4 I/O related S-Registers ................................................................................................... 81

4.5 S-Registers Defining the Functionality of the Module ..................................................... 90

4.6 Advanced Settings ....................................................................................................... 104

5 BUILD IN FUNCTIONALITY ........................................................................................... 112

6 ETRX357 POWER CONSUMPTION (PROVISIONAL DATA) ........................................ 115

7 NOTES ON ENERGY LEVELS AND LQI ....................................................................... 116

7.1 Interpreting LQI ............................................................................................................ 116

7.2 Interpreting RSSI Energy Levels .................................................................................. 117

8 TRADEMARKS ............................................................................................................... 118

9 DISCLAIMER .................................................................................................................. 118

10 CONTACT INFORMATION ............................................................................................. 118

R309 AT Commands

11 REFERENCES ................................................................................................................ 118

12 APPENDIX A. FORMING A SECURE NETWORK ........................................................ 119

13 APPENDIX B. BOOTLOADING NEW FIRMWARE ....................................................... 120

13.1 Bootloading through the serial port ............................................................................... 120

13.2 Bootloading over the air ............................................................................................... 121

R309 AT Commands

1 Introduction

1.1 The first step Send the command “ATI” to a module to find its firmware version. If it is not R309 then you should

refer to the correct version of the AT command manual, or send an e-mail to

zigbeesupport@telegesis.com requesting a copy of the R309 firmware file. All four variants of the

ETRX357 module share the same file. Alternatively if your module has R309 and you prefer a different version, this can be provided on

request. All the standard AT command set firmware files are free of charge to users who already have the

ETRXn devices, but they must only be used on Telegesis modules.

1.2 Module overview

This document describes the AT-Command interface firmware of the ETRX3 series ZigBee PRO wireless meshing modules. It applies to the R309 firmware, which can be loaded on to all products of the ETRX3 module series, for example:

- ETRX357, ETRX357-LR, ETRX357-LRS

- ETRX357HR, ETRX357HR-LR, ETRX357HR-LRS

- ETRX3585, ETRX3587 and ETRX3588

- ETRX3USB

- ZigBee Communications Gateway The Telegesis ZigBee modules have been designed to be built into any device and provide a low

cost, low power ZigBee solution based on the industry leading EmberZNet ZigBee stack. Integration into a wide range of applications is made easy using a simple AT-style software interface and advanced hardware design.

No RF experience or expertise is required to add this powerful wireless networking capability to your products. Telegesis ZigBee modules offer fast integration opportunities and the shortest possible time to market for your product.

Important note Using the AT-Command interface described in this document can shorten the time to market

significantly, however customers using the range of Telegesis modules also have the option of using Ember’s EZSP interface firmware or of developing custom firmware using the Ember Development tools.

1.3 Document Overview

This document is meant as an AT-Command and S-Register reference for R3xx revisions of the firmware based on EmberZNet3.x and EmberZNet4.x. In order to learn how your products can benefit from wireless mesh networking please also refer to the following documents:

ETRX3 Product Manuals

R309 AT Commands

R3xx Firmware User Guide Migration guide for existing R2xx firmware customers ETRX3 Development Kit User Guides Application notes from www.telegesis.com The ETRX3 Product Manuals concentrate on the hardware specification of the modules. The

Development Kit Product Manuals contain all of the information required to set up your development kit and run firmware upgrades where necessary.

1.4 Network topology

A network consists of a ZigBee Coordinator (ZC) which started the network, ZigBee Routers (ZR) and ZigBee End Devices (ZED). There do not have to be any routers (other than the coordinator, which functions as a router) or end devices in any given network. Each router can support up to 30 end devices in any combination of non-sleepy, sleepy and mobile End Devices. The network is always formed as a mesh according to the ZigBee PRO featureset of the ZigBee standard; the tree structure is not available.

By default the module joins a PAN as a router, but modifying register S0A allows you to define it as an end device. The coordinator is simply the device that first establishes the PAN, and it should not be allowed to leave the PAN as it is not possible for a node that is already joined to the PAN to take over the role of a coordinator or Trust Centre.

1.5 The ADCs

The ETRX357 can operate up to 4 ADCs, which are individually enabled by settng the appropriate bits in register S15. A reading is taken each time one of the registers S1F-22 is read, or when a built-in function is executed which reads an ADC. If bit 8 of S15 is set the 1.2V Vref level is presented at pin PB0 for the brief interval while the reading is taken.

Mode: single-ended Range: 0-1200mV Resolution: 14 bits Units: 1 LSB = 0.1mV Max load on PB0: 1mA

1.6 RTC Related Commands

The module runs a real time clock which can be set, read and synchronized against a time server with the commands shown in this chapter. Please note that the basis of the real time clock is an on-chip RC timer which gets calibrated against the external quartz crystal. Overall the accuracy is not high and will vary with temperature, so if an accurate RTC is to be maintained frequent resynchronization with a time server is required.

1.7 A Note on ZigBee® Compliance

The Telegesis R300 firmware has been tested and certified for MSP (manufacturer specific profile) compliance by a test house appointed by the ZigBee Alliance.

R309 AT Commands

This certification includes tests guaranteeing that:

- Modules running the Telegesis AT-Command set will not interfere with existing ZigBee Networks in a malicious way

- Modules running the Telegesis AT-Command set can join a 3rd party ZigBee PRO network and use its routing capabilities

- Modules running the Telegesis AT-Command set can allow 3rd party nodes to join into a network consisting of Telegesis nodes and use its routing capabilities

In addition to implementing a manufacturer specific application profile the AT-Command set allows for transparency allowing communication with 3rd party nodes running any public application profile. In addition to this a transparent endpoint has been added allowing a host processor to implement any public application profile in fully transparent mode.

If you want to use the term ZigBee or the ZigBee Logo in your product documentation the current regulations state that you have to

(i) Be at least an adopting member of the ZigBee Alliance in the year you release your product (ii) Implement a public application profile

If you intend to get your product certified feel free to contact Telegesis for additional information. Also if you intend to build a product compliant to a public application profile (e.g. Home Automation, Smart Energy) feel free to contact us to discuss your options.

1.8 Important notes

1.8.1 Hardware compatibility

R2xx firmware will not run on the ETRX3 series of modules.

1.8.2 Unexpected start-up in bootloader mode

The bootloader in the ETRX357 can be triggered using the command AT+BLOAD as described in section 2, but it can also be triggered in hardware. If the PA5 pin is pulled low during the boot-up of the module, the module will also enter the bootloader, so exercise caution when doing hardware design and ensure that this pin is not grounded during start-up and reset. If unused the pad can be left floating and a pull-up is not required.

1.8.3 Compatibility with other devices

Most features of the R3xx Telegesis AT-Command line Interpreter are part of a Manufacturer Specific Profile using the ZigBee PRO feature set of ZigBee 2007. Interoperability with other devices that use the ZigBee PRO featureset is limited to a number of transparent commands.

R3xx is not compatible with earlier versions of ZigBee which do not implement the ZigBee PRO featureset, including Telegesis R2xx firmware. Also, it is not compatible with the ZigBee Smart Energy profile as it lacks the required security key.

1.8.4 Persistence of network parameters

Once a device has joined a network as a coordinator, router or end device, it will retain its network parameters if it is powered off and on again. It will still be a member of its original PAN, assuming that PAN still exists, though an end device may need to find a new parent and it may have missed an update of the network key. Certain S-registers will have been reset to default values, though, which may change an end device’s power mode for example.

R309 AT Commands

Read Command

ATXXX?

Commands ending with a ‘?’ return the currently set value of the

parameter or parameters

Write Command

ATXXX=<…>

This command sets user-definable parameters as indicated by the ‘=’ sign.

Execute Command

ATXXX

This command executes routines of the module and returns parameters

2 AT Style Command Conventions

To simplify the communication with the modules, an AT-style command set, similar to the industry standard Hayes modem control language, is used.

Each command must be preceded by the "AT" or "at" prefix. To terminate a command enter <CR>. Any data not following this pattern is either not accepted by the module or will cause an error message in response. Every command must be terminated with a <CR>, they cannot be concatenated.

Commands are followed by an optional response that includes <CR><LF><Response><CR><LF> and/or a prompt <CR><LF><Prompt><CR><LF> where the prompt could also be an error message.

Example:

ATS00?<CR> <CR><LF>FFFF<CR><LF> <CR><LF>OK<CR><LF>

It is recommended to wait for an “OK” or “ERROR:XX” prompt before issuing the next command. Any data which is prompted to the user is delivered in the format <CR><LF><prompt><CR><LF>.

Unless disabled in S0E or S0F prompts may appear whenever the corresponding event occurs. Example:

A prompt intersecting a command being entered will not affect the command itself. Throughout this document, only the responses and prompts are presented, <CR><LF> are omitted

intentionally. Sequences of AT commands in a single line are not supported. The ETRX357 features a 128-byte FIFO to buffer incoming characters from the host processor,

which is sufficient to hold even the longest possible command. The ETRX357 features a 256-byte FIFO buffer for incoming radio messages, which allows rapid reception of multiple messages without loss of characters. To prevent a buffer overflow XON/XOFF handshaking is used. Optional hardware handshaking can be enabled as described in the register description of S12 in section 4.

Table 1: Types of AT commands

When bit 7 of S12 is set each individual reply or prompt is additionally started with the STX and ended with the ETX character to aid the interpretation of the incoming strings on a host processor.

R309 AT Commands

XX

8-bit hexadecimal number. Valid characters are 0-9, a-f and A-F

XXXX

16-bit hexadecimal number. Valid characters are 0-9, a-f and A-F

n

Number from 0-9

s

Sign

b

Bit (0 or 1)

c

character

<PID>

16-bit hexadecimal PAN ID (0000 to FFFF)

<EPID>

64-bit hexadecimal extended PAN ID

decimal channel (802.15.4 channel 11-26)

8 character password

<EUI64>

64-bit IEEE 802.15.4 address in hexadecimal

32-bit hexadecimal number representing the reading of S1A

<data>

Custom Data

A list of 16 bit cluster identifiers in hexadecimal representation

The Firmware Revision Number

2.1 Parameters

Each parameter must be entered in the correct format for any of the AT commands to execute correctly. Optional parameters are marked with square brackets […].

Table 2: Different formats of parameters

R309 AT Commands

Prompt Overview

OK

OK terminator

ERROR:XX

Error number XX occurred

ACK:XX

Acknowledgement for message XX was received

NACK:XX

Acknowledgement for message XX was not received

POLLED:XX

Shown on an end device when it polls its parent and S11 bit D is set. XX codes are:

00 - Success 31 - no data pending on host 66 - poll could not be executed 40 - no ack from parent

SR:XX,<EUI64>,<NWK addr>,…

Route Record Message received

BCAST:[<EUI64>,]XX=<data> [,<RSSI>,<LQI>]

A Broadcast with XX characters has been received

MCAST:[<EUI64>,]XX=<data> [,<RSSI>,<LQI>]

A Multicast with XX characters has been received

UCAST:[<EUI64>,]XX=<data> [,<RSSI>,<LQI>]

A Unicast with XX characters has been received

INTERPAN:<ProfileID>,<ClusterID>, <Msgtype>,<Option>,[GroupID],<PanID>, <SrcAddr>,<MsgLength>,<Msg>

The device has received an interpan message <ProfileID> - 16 bit hex <ClusterID> - 16 bit hex <Msgtype> - 8 bit hex

0x00 – Unicast 0x08 – Broadcast 0x0C- Multicast

<Option> - 16 bit hex. If it is 0x0002 the <SrcAddr> will be source long address, and otherwise it is source network address

[GroupID] – 16 bit hex, shown if the message is sent to a group

<PanID> - 16 bit hex, source PAN ID <SrcAddr> - 16 bit hex source node ID or EUI <MsgLength> - 8 bit hex, message length <Msg> - received message in hex format

RAW:snn,<data>

A raw message has been received with strength snn dBm

SDATA:[<EUI64>,],<ioread>,<ADC0>, <ADC1>,<sequenceNo>,<Vcc>

A data message has been received at the sink. ADC data is ADC0 & ADC1

2.2 Prompt Overview

The following prompts can show up during the operation of the ETRX357 modules. Most of the prompts can be disabled using register S0E and S0F.

R309 AT Commands

Prompt Overview

FN130:[<EUI64>],<NWK addr>,<ioread>, <sequence no>,<S46>,[<ADC0>], [<ADC1>],[<ADC3>],[<ADC3>]

A data message has been received at the sink. The number of ADC data fields depends on how many ADCs are activated at the sender

FFD:<EUI64>,<NWK addr>

A router announcing itself

SED:<EUI64>,<NWK addr>

A sleepy end device announcing itself

MED:<EUI64>,<NWK addr>

A mobile sleepy end device announcing itself

ZED:<EUI64>,<NWK addr>

An end device announcing itself

NEWNODE: <NWK addr>,<EUI64>, <Parent NWK addr>

Shown on Coordinator: New node has been given permission to join the PAN. NB joining is not

complete until an “FFD” prompt or similar is

received

LeftPAN

Local Node has left the PAN

LostPAN

End Device has lost contact with Parent

JPAN:<channel>,<PID>,<EPID>

Local Node has joined PAN with given parameters

NODELEFT: <NWK addr>,<EUI64>

A device has left the PAN (shown on COO only)

ADSK:<EUI64>,<NWK addr>

Received Sink Advertisement

SREAD:<NWK addr>,<EUI64>,<Register>, <errorcode>[=<Data>]

Reply to a remote S Register Read operation

SWRITE:<NWK addr>,<EUI64>,<errorcode>

Reply to a remote S Register Write operation

Bind:<NWK addr>,<status>

Create Binding Status

Unbind:<NWK addr>,<status>

Delete Binding Status

End Device Bind:<NWK addr>,<status>

End device binding status

DataMODE:<NWK addr>,<EUI64>

Datamode has been opened remotely

DataMODE:<NWK addr>,<EUI64>, <errorcode>

Response to an attempt to open data mode

OPEN

Data mode is open

CLOSED

Data mode is closed

TRACK:<EUI64 R>,<EUI64 S>,<RSSI>, <i/o read>,<ADC0>,<ADC1>,<Vcc>,<S46>

Tracking message: EUIs of receiver and sender, RSSI, input data, Vcc & S46 counter of sender (only the low-order 16 bits of S46 are shown)

TRACK2:<EUI64 R>,<EUI64 S>,<RSSI>, <I/O read>,<S46>

Tracking message: EUIs of receiver and sender, RSSI, I/O data, and S46 counter of sender

PWRCHANGE:XXXX

Local node has changed Power Mode to XXXX

AddrResp:<errorcode> [,<NWK addr>,<EUI64>]

Response to an address request (also triggered when finding source routes)

RX:<EUI64>,<NWK addr>,<profileID>, <destinationEndpoint>,<SourceEndpoint>, <clusterID>,<length>:<payload> [,<RSSI>,<LQI>]

An incoming message not addressed to the AT command endpoint. EUI64 is only shown if included in network frame header

NM:ES REPORT WARNING

More than 16 energy scan reports have been recently received by the network manager indicating high packet loss

ENTERING BLOAD

Passthrough bootloading has been initiated from another node

Table 3: Prompt Overview

R309 AT Commands

Device Types

ZigBee Naming Convention

COO

Coordinator

ZigBee Coordinator (ZC)

FFD

Router

ZigBee Router (ZR)

ZED

End Device (non sleepy)

ZigBee End Device (ZED)

SED

Sleepy End Device

MED

Mobile Sleepy end Device

2.3 Device Overview

2.3.1 ZigBee types

Table 4 gives an overview of the ZigBee device types mentioned in this document.

Table 4: Device Overview

The terms Full Function device (FFD) and Reduced Function Device (RFD) are obsolete, but the abbreviations are retained in the R309X firmware to avoid problems with users’ legacy application software.

Each ETRX357 coordinator or router can support up to 30 End Devices, in any combination of Sleepy End Devices and Mobile End Devices.

Only end devices should be put into a low-power state because routers and the coordinator must always be powered up to maintain the network connectivity. ZigBee End Devices do not poll for data, instead their incoming messages are relayed immediately by their parent without being buffered. This means that ZEDs must not be put into a sleep mode.

2.3.2 Non-ZigBee types Sink. The sink is a Telegesis feature. When a node is defined as a sink by setting S10 bit 4, it

can broadcast its address to the rest of the network. Other nodes can then send messages to the sink node using AT+SCAST or various built-in functions. This simplifies the application software since it is not necessary to know the EUI64 of the sink in advance.

Routers discover the sink when (1) they receive a regular advertisement broadcast from the sink (2) they are commanded to send a message without knowing the sink address and bit 8 of S10 is set (the first sink-cast message is therefore lost) (3) the AT+SSINK command is used.

To reduce traffic to end devices they do not receive the advertisement broadcasts and are not informed of the sink address when they join the PAN. Instead they automatically search for the sink the first time they send a message to it, even if bit 8 of S10 is not set. The first message returns an error, though, as the sink address is unknown at that stage.

2.4 Addressing modes

Many of the AT commands take a device address as a parameter, which can usually be expressed in several different formats.

EUI64. 16 hexadecimal characters. This is flashed on to the chip at manufacture and cannot be changed by the user. This can be compared to the permanent MAC address of an IP-based device.

Network address. 4 hexadecimal characters. This is allocated to the device when it joins the PAN and cannot be changed or preset, except that 0x0000 is always the coordinator. It is analogous to a temporary IP address. Otherwise known as the Node ID.

R309 AT Commands

Address table entry. Range 00-06. Entry 05 is a sink address, entry 06 is the source address of the last received UCAST, SCAST or MCAST that arrived at endpoint 1 with profile C091 and cluster 0002 (ie the default Telegesis parameters).

Binding table entry. Range 10-24 (hexadecimal). Entry FE causes a search of the table for the first entry whose source endpoint and cluster ID matches registers S40 and S42.

FF. In many commands address FF represents the local device.

R309 AT Commands

Command Overview

Module control and configuration

ATI

Display Product Identification Information

ATZ

Software Reset

AT+REMZ

Reset Remote Node

AT&F

Restore Factory Defaults

AT+BLOAD

Enter The Bootloader Menu

AT+PASSTHROUGH

Pass new Firmware Image To Remote Node

AT+RECOVER

Recover From A Failed Clone Attempt

ATS

S-Register Access

ATREMS

Remote S-Register Access

ATSALL

Remote S-Register Access

AT+TOKDUMP

Display All S-Registers

Network control and configuration

AT+ESCAN

Scan The Energy Of All Channels

AT+EN

Establish Personal Area Network

AT+PANSCAN

Scan For Active PANs

AT+JN

Join Network

AT+JPAN

Join Specific PAN

AT+SJN

Silent Join

AT+DASSL

Disassociate Local Device From PAN

AT+DASSR

Disassociate Remote Node From PAN (ZDO)

AT+N

Display Network Information

AT+NTABLE

Display Neighbour Table (ZDO)

AT+RTABLE

Display Routing Table (ZDO)

AT+IDREQ

Request Node’s Network address (ZDO)

AT+EUIREQ

Request Node’s EUI (ZDO)

AT+NODEDESC

Request Node’s Descriptor (ZDO)

AT+POWERDESC

Request Node’s Power Descriptor (ZDO)

AT+ACTEPDESC

Request Node’s Active Endpoint List (ZDO)

AT+SIMPLEDESC

Request Endpoint’s Simple Descriptor (ZDO)

AT+MATCHREQ

Find Nodes which Match a Specific Descriptor (ZDO)

AT+ANNCE

Announce Local Device in the Network (ZDO)

AT+SR

Set Source Route To Remote Device

AT+FNDSR

Find The Source Route To A Remote Device

AT+POLL

Poll For Data From Parent

AT+REJOIN

Rejoin The Network

AT+SN

Scan Network

AT+KEYUPD

Update the Network Key (ZDO)

AT+BECOMETC

Make Local Device the Trust Centre

AT+BECOMENM

Make the local device Network Manager

AT+CCHANGE

Change the network’s channel

2.5 AT Command Overview

The following table gives a quick reference of all commands available.

R309 AT Commands

Command Overview (continued)

Messaging

AT+ATABLE

Display Address Table

AT+ASET

Set Address Table Entry

AT+MTABLE

Display Multicast Table

AT+MSET

Set Multicast Table Entry

AT+BCAST

Transmit A Broadcast

AT+BCASTB

Transmit A Broadcast Of Binary Data

AT+UCAST

Transmit A Unicast

AT+UCASTB

Transmit A Unicast Of Binary Data

AT+SCAST

Transmit Data To The Sink

AT+SCASTB

Transmit Binary Data To The Sink

AT+SSINK

Search For A Sink

AT+MCAST

Transmit A Multicast

AT+MCASTB

Transmit A Multicast Of Binary Data

AT+DMODE

Enter Data Mode (Serial Link Mode)

+++

Leave Data Mode

AT+IDENT

Play A Tune On Remote Devboard

AT+SENDUCAST

Send A Raw ZCL/ZDO Unicast

AT+SENDUCASTB

Send A Raw Binary ZCL/ZDO Unicast

AT+SENDMCAST

Send A Raw ZCL/ZDO Multicast or Broadcast

AT+SENDMCASTB

Send A Raw Binary ZCL/ZDO Multicast or Broadcast

AT+INTERPAN

Send an Interpan Command

AT+RDATAB

Send Binary Raw Data

Binding Management

AT+LBTABLE

Display Local Binding Table

AT+BSET

Set Local Binding Table Entry

AT+BCLR

Clear Local Binding Table Entry

AT+BTABLE

Display Binding Table (ZDO)

AT+BIND

Create Binding on Remote Device (ZDO)

AT+UNBIND

Delete Binding on Remote Device (ZDO)

AT+EDBIND

Request End Device Binding (ZDO)

Time-related commands

AT+SETTIME

Set the Local Time

AT+GETTIME

Get the Local Time

AT+SYNCTIME

Synchronize the Local Time with Time Server

Table 5: Command Overview

R309 AT Commands

I – Display Product Identification Information

Execute Command

ATI

Response

Telegesis <DeviceName> R<Firmware Revision> <EUI64> OK

Where <DeviceName> is the order code of the device, <Firmware Revision> is the firmware

revision and <EUI64> is the Device’s IEEE

802.15.4 identifier

SW release

R300 ●

Z – Software Reset

Execute Command

ATZ

Response

JPAN:<channel>,<PID>,<EPID> OK

or

OK

Module Performs a software reset All non-volatile S Registers keep the user defined values, if the module was part of a PAN it will remain part of it.

SW release

R300 ●

2.6 Module Control & Configuration Commands

R309 AT Commands

+REMZ – Reset Remote Node (ETRX3 only)

Execute Command

AT+REMZ:<address>

Where <address> can be the remote node’s

EUI64, Network address or address table index

Use on

All Devices

Response

SEQ:XX OK

or

ERROR<errorcode>

Prompt

ACK:XX

or NACK:XX

<errorcode> represents the error code explained in section 3. Performs a soft reset on a remote node.

SW release

R309 ●

&F – Restore Factory Defaults

Execute Command

AT&F

Response

Module Performs a factory reset All non-volatile S Registers are updated with their factory defaults and the node leaves the network it is currently joined to.

SW release

R300 ●

+BLOAD – Enter The Bootloader Menu

Execute Command

AT+BLOAD

Response

The device leaves the AT command line and enters the bootloader menu for downloading new firmware. A description of the bootloading process can be found in the Development Kit Product Manual. Please note that the bootloader will run at a baudrate of 115k2, no parity, 8 data bits regardless of the current serial port settings.

SW release

R300 ●

R309 AT Commands

+PASSTHROUGH – Pass new Firmware Image To Remote Node

Execute Command

AT+PASSTHROUGH:<EUI64>,<password>

Use on:

Source: FFD, COO Destination: FFD, COO, ZED

Notes

Passthrough is not possible to SEDs or MEDs or over multiple hops. The default password for R3xx nodes is “password”. A description of the passthrough process can be found in the Development Kit Product Manual; it is the same procedure as cloning. The ETRX357(HR)-LRS module cannot be reliably upgraded by the passthrough process

Response

PASSTHROUGH BLOAD...

Please start .ebl upload image...

Remote Response

ENTERING BLOAD

or

ERROR<errorcode>

Where <errorcode> represents the error code explained in section 3.

<password> represents the remote node’s

8-character password. After completion a soft reset is caused on the remote end.

SW release

R304 ●

+RECOVER – Recover From A Failed Clone or Passthrough Attempt

Execute Command

AT+RECOVER

Use on:

Source: FFD, COO Destination: All device types

Note

Use this command in cases where the Passthrough Bootloading operation was interrupted and the target device therefore remains in the bootloader. In case the target device has been reset channel 13 must be used for recovering. For more information on over-the-air firmware upgrading please refer to the Development Kit Manual.

Response

Recovering…

or

ERROR<errorcode>

Where <errorcode> represents the error code explained in section 3. Enters Passthrough mode to a remote node which is already in the bootloader.

SW release

R300 ●

R309 AT Commands

S – S-Register Access

Read Command

ATSXX[x[x]]?

Examples

ATS00? ATS0AE? ATS1812?

XX is the S-Register which is to be read. As an option for all 16 bit registers it is also possible to address an individual bit only by specifying the bit number [x]. For all 32 bit registers it is possible to address an individual bit by specifying the bit number in hexadecimal [xx]

Response

<data> OK

or ERROR:<errorcode> The module displays the contents of S-register

xx or an error message, where <errorcode> represents the error code explained in section 3. All 16- and 32-bit registers can also be accessed bit by bit. In order to do this [x[x]] may specify the bit which is to be read. The result when reading a single bit will always be 0 or 1.

Write Command

ATSXX[x[x]]=<data>[,<password>]

Examples

ATS00=3FFC ATS0AE=1:password

Notes

Some S-Registers require a password for write access. See S-Register description for details.

The default password for R3xx is

“password”. Some S-Registers are read-only and will return an error if you are trying to write to them. When writing an individual bit by specifying [x[x]], <data> can only be either 0 or 1.

Response

OK or ERROR:<errorcode> The data is written to S-register number XX and

if applicable stored in non-volatile memory. The data format for each individual S-Register is given in the S-Register description. <errorcode> represents the error code explained in section 3. For all 16- and 32-bit registers individual bits can also be set or cleared by specifying the bit using hexadecimal [x[x]] and setting it to either 0 or 1.

SW release

R300 ●

R309 AT Commands

REMS – Remote S-Register Access

Read Command

ATREMS:<address>,XX[X[x]]?

Examples

ATREMS:000D6F00000AAC93,00? ATREMS:000D6F00000AAC93,0AE? ATREMS:000D6F00000AAC93,1812?

Where <address> can be the remote node’s

EUI64, Network address or address table index and XX is the S-Register which is to be read. As an option for all 16 bit registers it is also possible to address an individual bit only by specifying the bit number [X]. For all 32 bit registers it is possible to address an individual bit by specifying the bit number in hexadecimal [xx] The result when reading a single bit will always be 0 or 1.

Note

Also the local node can be the target of this command (e.g. use address table entry FF as the address)

Response

SEQ:XX OK

or ERROR:<errorcode> The module asks for the contents of the remote

S-register using a unicast. The sequence number of the unicast is displayed (an ACK or NACK prompt will follow). <errorcode> represents the error code explained in section 3.

Prompt

SREAD:<Network address>,<EUI64>,<Register>, <errorcode>[=<Data>]

Where Network address is the remote Network address, EUI64 is the remote EUI64, Register is the S-Register which was read and <errorcode> is indicating the success (00) or failure of the read operation. The contents of the remote SRegister are following in case of a successful read only.

Write Command

ATREMS:<address>,XX[x[x]]=<data> [,<password>]

Examples

ATREMS:000D6F0000012345,00=3FFC ATREMS:000D6F0000012345,0AE=1:passwor d

Where <address> can be the remote node’s

EUI64, Network address or address table index and XX is the S-Register which is to be written. As an option for all 16- and 32-bit registers it is also possible to address an individual bit only by specifying the bit number [x[x]].

Notes

Some S-Registers require a password for write access. See S-Register description for details.

The default password for R3xx is

“password”. Some S-Registers are read-only and will return an error if you are trying to write to them. When writing an individual bit by specifying [x[x]], <data> can only be either 0 or 1.

Response

SEQ:XX OK

or ERROR:<errorcode> The data is written to the remote S-register

number XX and if applicable stored in nonvolatile memory. The data format for each individual S-register is given in the S-Register description. The sequence number of the unicast is displayed (an ACK or NACK prompt will follow). <errorcode> represents the error code explained in section 3.

Prompt

SWRITE:<Network address>,<EUI64>,<errorcode >

Where <Network address> is the remote Network address, <EUI64> is the remote EUI64. Only in case the errorcode is 00 the write operation has been completed successfully.

SW release

R302 ●

R309 AT Commands

SALL – Remote S-Register Access

Write Command

ATSALL:<group ID>,XX[x[x]]=<data> [,<password>]

Examples

ATSALL:FFFF,00=3FFC ATSALL:FFFC,0AE=1:password

Where group IDs are remote node’s multicast

IDs or FFFF - Broadcast to all devices FFFD - Broadcast to all non-sleepy devices FFFC – Broadcast to all Routers

Notes

Some S-Registers require a password for write access. See S-Register description for details.

The default password for R3xx is

“password”. Some S-Registers are read-only and cannot be written to.

Response

OK or ERROR:<errorcode> The data is written to the remote S-register

number XX on all nodes addressed by the multicast group ID. The data format for each individual S-register is given in the S-register description. <errorcode> represents the error code explained in section 3. For all 16- and 32-bit registers individual bits can also be set or cleared by specifying the bit using hexadecimal [x[x]] and setting it to either 0 or 1.

SW release

R300 ●

+TOKDUMP – Display All S-Registers

Execute Command

AT+TOKDUMP

Notes

Only used on the local node. You cannot display all the registers of a remote device.

Response

<data> OK

The module displays the contents of all local SRegisters. The data format for each individual S-register is given in the S-register description in section 4.

SW release

R300 ●

R309 AT Commands

+ESCAN – Scan The Energy Of All Channels

Execute Command

AT+ESCAN

Use on:

All nodes

Notes

Scanning all channels can take up to 4 seconds. The results are the background radio power in

each channel, not the RSSI of incoming ZigBee packets

Response

+ESCAN: 11:XX 12:XX … 26:XX OK

or ERROR:<errorcode> <errorcode> represents the error code explained

in section 3. XX represents the average energy on the respective channel (see description in Section 7). Channels masked out in S00 are not scanned.

SW release

R300 ●

+EN – Establish Personal Area Network

Execute Command

AT+EN

Use on:

All nodes which are not part of a PAN

Note

When issuing this command the local device becomes a Coordinator (and Trust Centre). Establishing a PAN can take up to 4 seconds. This command can only be executed if the local node is not part of a PAN already.

Response

JPAN:<channel>,<PID>,<EPID> OK

or ERROR:<errorcode>

<errorcode> represents the error code explained in section 3.

The local node becomes a coordinator and performs an energy scan on all channels selected in S00. It then starts a PAN with a random unused PAN ID and extended PAN ID on the quietest channel. If a PAN ID and/or extended PAN ID is specified in S02 or S03 the provided IDs are used instead of random ones, given the selected IDs are not already in use by other networks within range

SW release

R300 ●

2.7 Network Control & Configuration Commands

R309 AT Commands

+PANSCAN – Scan For Active PANs

Execute Command

AT+PANSCAN[:[b][,XXXX][,dd]]

When specifying a value of 0 or 1 for b only responses from nodes with the joining status set accordingly will be shown. Specifying a channel mask using XXXX will override the setting of S00 for this specific command. Using dd it is possible to modify the scan time per channel (default = 3).

(00 = 31ms, 01 = 46ms, 02 = 77ms, 03 = 138ms, 04 = 261ms, 05 = 507ms, 06 = 998ms)

Examples

AT+PANSCAN AT+PANSCAN:1 AT+PANSCAN:1,03 AT+PANSCAN:03 AT+PANSCAN:FF0F AT+PANSCAN:FF0F,03 AT+PANSCAN:1,FF0F AT+PANSCAN:1,FF0F,03

Use on:

All nodes

Note

Scanning for active PANs can take up to 4 seconds when dd=3

Response

+PANSCAN:<channel>,<PID>,<EPID>,XX,b OK

or

+PANSCAN:<channel>,<PID>,<EPID>,XX,b, <rssi>,<LQI>

OK

or ERROR:<errorcode> <errorcode> represents the error code explained

in section 2.10. The node gives a list of all PANs found. <channel> represents the channel, <PID> the PAN ID, <EPID> the extended PAN ID, XX the ZigBee stack profile (00 = Custom, 01 = ZigBee, 02 = ZigBee PRO) and b indicates whether the network is allowing additional nodes to join (1 = joining permitted). The node does not join any of the PANs found.

If bit E of S0F is set the response includes RSSI and LQI

SW release

R300 ●

R309 AT Commands

+JN – Join Network

Execute Command

AT+JN

Use on:

All nodes which are not part of a PAN

Note

Joining a PAN can take up to 4 seconds, depending on the number of channels which need scanning. This command can only be executed if the local node is not part of a PAN already.

Response

JPAN:<channel>,<PID>,<EPID> OK

or ERROR:<errorcode>

<errorcode> represents the error code explained in section 3. The local node scans all channels selected in register S00 for the existence of a PAN. When finding a PAN which allows joining it will automatically join via the router with the best signal quality. When registers S02 and S03 differ from the default value of all zeros the node will only join a PAN with the specified Pan ID and/or extended PAN ID.

Remote Action On the Trust Centre / Coordinator

Prompt

NEWNODE:<node EUI64>, <Network address>,<parent EUI64>

SW release

R300 ●

+JPAN – Join Specific PAN

Execute Command

AT+JPAN:<channel>,<PID or EPID>

Examples

AT+JPAN:20,1234 AT+JPAN:24,0793E14FFB220A38

Use on

All nodes which are not part of a PAN

Notes

This command can only be executed if the local node is not part of a PAN already. The JPAN command ignores the channel mask in register S00 and the PID and EPID settings in S02 and S03.

Response

JPAN:<channel>,<PID>,<EPID> OK

or ERROR:<errorcode>

<errorcode> represents the error code explained in section 3. The local node joins a particular PAN on <channel> with the specified <PID> or <EPID> via the router with an adequate signal quality and the fewest hops to the COO.

Remote Action On the Trust Centre / Coordinator

Prompt

NEWNODE:<node EUI64>, <Network address>,<parent EUI64>

SW release

R300 ●

R309 AT Commands

+SJN – Silent Join

Execute Command

AT+SJN:<channel>,<TC EUI64>, <NM Network address>,<nwk update ID>

“Silent” joining is joining via the commissioning

method. All data required to enter the network is provided to the node, so that no joining procedure itself is required. The node will appear in the target network without any joining procedure given the supplied data is correct. The node can only join as a router, not an end device

<channel> is a decimal number Other parameters are hexadecimal

Example

AT+SJN:11,000D6F00000AAAD0,AFFE,00

Use on

All joining Devices

Response

JPAN:<channel>,<PID>,<EPID> OK

or ERROR:<errorcode> >

<errorcode> represents the error code explained in section 3. The local node will become part of the network with the channel specified in <channel>, the trust centre EUI64 specified in <TC EUI64>, the Network address of the network manager specified in <NM Network address>, the 8 bit network update ID specified in <nwk update ID>, the network key provided in S08, the trust centre link key provided in S09, the PAN ID provided in S02 and the extended PAN ID provided in S03. Joining is still possible if the network update ID is incorrect. It is assumed that the key-sequence-number of the network key is 0 when issuing this command.

SW release

R305 ●

+DASSL – Disassociate Local Device From PAN

Execute Command

AT+DASSL

Note

Use with care on a Coordinator. It will not be able to rejoin the PAN

Use on

All Devices

Response

OK or ERROR<errorcode>

Prompt

LeftPAN

<errorcode> represents the error code explained in section 3. Instruct local device to leave the PAN.

SW release

R300 ●

R309 AT Commands

+DASSR – Disassociate Remote Node from PAN (ZDO)

Execute Command

AT+DASSR:<address>

Where <address> can be a node’s EUI64,

Network address or address table index

Note

Use with care when targeting a Coordinator. It will not be able to rejoin the PAN

Use on

All Devices

Remote Action

Node leaves PAN

Response

SEQ:XX OK

or ERROR:<errorcode>

<errorcode> represents the error code explained in section 3. Instruct device to leave the PAN.

Prompt

LeftPAN

SW release

R300 ●

+N – Display Network Information

Read Command

AT+N?

Use on

All Devices

Response

+N=<devicetype>,<channel>,<power>, <PID>,<EPID>

or +N=NoPAN followed by

OK

<devicetype> represents the node’s functionality in the PAN (FFD,COO,ZED,SED,MED), <power> the node’s output power in dBm, <channel> the IEEE 802.15.4 radio channel (11-

26), <PID> the node’s PAN ID and <EPID> the node’s extended PAN ID.

SW release

R302 ●

R309 AT Commands

+NTABLE – Display Neighbour Table (ZDO)

Read Command

AT+NTABLE:XX,<address>

Where XX is the start index of the remote LQI table and <address> can be the remote node’s EUI64, Network address or address table entry.

Note

Also the local node can be the target of this command (e.g. use address table entry FF as the address)

Use on

FFD, COO as the target device

Response

SEQ:XX OK or ERROR<errorcode>

This command requests the target node to respond by listing its neighbour table starting from the requested index. Can be used to find the identity of all ZigBee devices in the network including non-Telegesis devices.

Prompt (example)

NTable:<Network address>,<errorcode> Length:03 No.| Type | EUI | ID | LQI

00.| FFD | 000D6F000015896B | BC04 | FF

01.| FFD | 000D6F00000B3E77 | 739D | FF

02.| FFD | 000D6F00000AAD11 | 75E3 | FF

In this example the neighbour table of the remote node with the short ID shown in <Network address> contains three entries (hexadecimal), which are displayed. In case the table contains more than three entries it may be required to repeat this command and increase the index count until the full table is derived. In case of an error an errorcode other than 00 will be displayed and the prompt will end after the errorcode.

SW release

R302 ●

R309 AT Commands

+RTABLE – Display Routing Table (ZDO)

Read Command

AT+RTABLE:XX,<address>

Where XX is the start index of the remote Routing table and <address> can be the remote node’s EUI64, Network address or address table entry.

Note

Also the local node can be the target of this command (e.g. use address table entry FF as the address)

Use on

FFD, COO as the target device

Response

SEQ:XX OK or ERROR<errorcode>

This command requests the target node to respond by listing its routing table starting from the requested index.

Prompt (example)

RTable:<Network address>,<errorcode> Length:40 No.| Dest | Next | Status

00.| 1234 | ABCD | 00

01.| 4321 | 739D | 00

02.| 0000 | 0000 | 03

In this example the routing table of the remote node with the short ID shown in <Network address> contains 64 entries (hexadecimal 0x40), of which the first three are displayed. When the table contains more than the displayed entries it may be required to repeat this command and increase the index count until the full table is derived. The status shown is as described in table 2.128 of the ZigBee Specification. In case of an error an errorcode other than 00 will be displayed and the prompt will end after the errorcode.

SW release

R303 ●

R309 AT Commands

+IDREQ – Request Node’s Network address (ZDO)

Execute Command

AT+IDREQ:<Address>[,XX]

Where <Address> can be a node’s EUI64, or

address table entry and XX is an optional index number. In case an index number is provided, an extended response is requested asking the remote device to list its associated devices (ie children). Sends a broadcast to obtain the specified Device’s Network address and optionally also elements of its associated devices list.

Note

Providing FF as an address table entry addresses the local node

Use on

All Devices

Response

OK

or ERROR:<errorcode> <errorcode> represents the error code explained

in section 3.

Prompt

AddrResp:<errorcode> [,<Network address>,<EUI64>] [nn. <Network address>]

In case of an error an errorcode other than 00 will be displayed and the prompt will end after the errorcode.

<EUI64> is the Remote node’s EUI64 and

<Network address> is its Network address. In case an extended response has been requested the requested Network addresses from the associated devices list are listed as well.

SW release

R302 ●

R309 AT Commands

+EUIREQ – Request Node’s EUI64 (ZDO)

Execute Command

AT+EUIREQ:< Address>, <Network address>[,XX]

Where <Address> is the EUI64, Network address or address table entry of the node which is to be interrogated about the node with the Network address specified in <Network address>. XX is an optional index number. In case an index number is provided, an extended response is requested asking the remote device to list its associated devices (ie children).

Sends a unicast to obtain the specified device’s

EUI64 and optionally also elements of its associated devices list (extended response).

Note

Providing FF as an address table entry addresses the local node. To find the EUI64 of an end device use its parent’s address as the <Address> parameter.

Use on

All Devices

Response

SEQ:XX OK

or ERROR:<errorcode> <errorcode> represents the error code explained

in section 3.

Prompt

AddrResp:<errorcode> [,<Network address>,<EUI64>] [dd. <Network address>]

In case of an error an errorcode other than 00 will be displayed and the prompt will end after the errorcode.

<EUI64> is the Remote node’s EUI64 and

<Network address> is its Network address. In case an extended response has been requested the requested Network addresses from the associated devices list are listed.

As with all unicasts after successful transmission the sequence number of the unicast is stated

using the “SEQ:XX” prompt. When

acknowledged (or not) the accompanying “ACK:XX” (or “NACK:XX”) prompt is displayed.

SW release

R302 ●

R309 AT Commands

+NODEDESC – Request Node’s Descriptor (ZDO)

Execute Command

AT+NODEDESC:<Address>, <Network address>

Where <Address> is the EUI64, Network address or Address table entry of the node which is to be interrogated about the node with the Network address specified in <Network address>.

Sends a unicast to obtain the specified device’s

node descriptor.

Note

Providing FF as an address table entry addresses the local node

Use on

All Devices

Response

SEQ:XX OK

or ERROR:<errorcode>

<errorcode> represents the error code explained in section 3.

Prompt (example)

NodeDesc:<Network address>,<errorcode> Type:FFD ComplexDesc:No UserDesc:No APSFlags:00 FreqBand:40 MacCap:8E ManufCode:1010 MaxBufSize:52 MaxInSize:0080 SrvMask:0000 MaxOutSize:0080 DescCap:00

In case of an error an errorcode other than 00 will be displayed and the prompt will end after the errorcode. <Network address> is the Remote node’s Network address. In addition the node descriptor is displayed. The individual fields of the Node Descriptor are described in section 2.3.2.3 of the ZigBee specification.

As with all unicasts after successful transmission the sequence number of the unicast is stated

using the “SEQ:XX” prompt. When

acknowledged (or not) the accompanying “ACK:XX” (or “NACK:XX”) prompt is displayed.

SW release

R302 ●

Telegesis ETRX357-LR, ETRX357, ETRX3 Series, ETRX357-LRS, ETRX357HR Command Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

1 Introduction

1.1 The first step Send the command “ATI” to a module to find its firmware version. If it is not R309 then you should

1.2 Module overview

1.3 Document Overview

1.4 Network topology

1.5 The ADCs

1.6 RTC Related Commands

1.7 A Note on ZigBee® Compliance

1.8 Important notes

1.8.1 Hardware compatibility

1.8.2 Unexpected start-up in bootloader mode

1.8.3 Compatibility with other devices

1.8.4 Persistence of network parameters

2 AT Style Command Conventions

2.1 Parameters

2.2 Prompt Overview

2.3 Device Overview

2.3.1 ZigBee types

2.3.2 Non-ZigBee types Sink. The sink is a Telegesis feature. When a node is defined as a sink by setting S10 bit 4, it

2.4 Addressing modes

2.5 AT Command Overview

2.6 Module Control & Configuration Commands

2.7 Network Control & Configuration Commands