Application Note AND9360/D
AX5051 AXRadio V2 API
Software Manual
Revision 1
2
TA B L E
OF
CONTENTS
1.Introduction........................................................................................................... 3
2.Prerequisites..........................................................................................................3
3.Constants...............................................................................................................4
3.1.Operating Modes..............................................................................................4
3.2.Error Codes..................................................................................................... 5
3.3.Status Change Codes........................................................................................6
4.Functions...............................................................................................................7
4.1.uint8_t axradio_init(void)..................................................................................7
4.2.uint8_t axradio_cansleep(void)..........................................................................7
4.3.uint8_t axradio_set_mode(uint8_t mode)............................................................8
4.4.uint8_t axradio_get_mode(void)........................................................................8
4.5.uint8_t axradio_set_channel(uint8_t chnum).......................................................8
4.6.uint8_t axradio_get_channel(void).....................................................................9
4.7.uint8_t axradio_get_pllrange(void) uint8_t axradio_get_pllrange_tx(void) ..............9
4.8.void axradio_set_local_address(const struct axradio_address_mask *addr).............9
4.9.void axradio_get_local_address(struct axradio_address_mask *addr).....................9
4.10.uint8_t axradio_set_freqoffset(int32_t offs).....................................................10
4.11.int32_t axradio_get_freqoffset(void)...............................................................10
4.12.int32_t axradio_conv_freq_tohz(int32_t f).......................................................10
4.13.int32_t axradio_conv_freq_fromhz(int32_t f)...................................................10
4.14.int32_t axradio_conv_timeinterval_totimer0(int32_t dt) ....................................10
4.15.uint32_t axradio_conv_time_totimer0(uint32_t dt) ...........................................10
4.16.uint8_t axradio_transmit(const struct axradio_address *addr, const uint8_t *pkt,
uint16_t len).......................................................................................................11
4.17.uint8_t axradio_agc_freeze(void) uint8_t axradio_agc_thaw(void) ......................11
4.18.void axradio_statuschange(const __xdata struct axradio_status *st)...................12
5.Static Configuration Items......................................................................................12
5.1.extern const __code uint8_t axradio_maclen;.................................................... 12
5.2.extern const __code uint8_t axradio_addrlen;....................................................12
6.Example usage code..............................................................................................13
6.1.Simple Asynchronous......................................................................................13
6.1.1.Transmitter.............................................................................................13
6.1.2.Receiver................................................................................................. 14
7.Files.................................................................................................................... 16
8.Contact Information...............................................................................................17
Introduction
1. I N T R O D U C T I O N
This document describes axradio. Axradio is intended to be an easy to use “driver” for
AXSEM Radio Chips, such as the AX5043 and AX5051, allowing the user to focus on his
product functionality and not the details of the radio link.
The API consists of a header file, axradio.h, providing functions for transmitting and
receiving packets, and switching the radio into different modes.
Most of the transceiver configuration is computed by AXRadioLab and stored in non-volatile
memory; it will not be changeable by the firmware. These items include:
•
Radio PHY configuration (except for channel)
•
Radio MAC (Frame Format) configuration (except actual addresses)
Some items should be runtime configurable. Items include:
•
Channel Number
•
Actual MAC Addresses
2. P R E R E Q U I S I T E S
AXRadio V2 uses the Wakeup Timer facilities of LibMF (libmfwtimer.h). These facilities are a
superset of the timing functions of AXRadio V1, but are much more flexible; they provide:
•
2 Timers, a slow but persistently running timer for events that need to survive sleep,
and a fast but switched off during sleep timer for short intervals
•
Multiple events per timer are supported
•
Not only usable for AXRadio – also supports user events
•
Mechanism for scheduling callbacks from interrupt context which run in main context
www.onsemi.com
AND9360/D
3
4
Prerequisites
•
Less overhead (assembly implementation where C compiler generated code was too
inefficient)
In order for the LibMF Wakeup Timer to work properly, the user should not use enter_sleep
and enter_standby directly, but should use wtimer_idle instead. Also, during long running
computations, wtimer_idle should be called periodically to allow pending callbacks to run.
3. C O N S T A N T S
3.1. O P E R A T I N G M O D E S
Mode
Description
AXRADIO_MODE_
OFF
The radio is off, but in a configured state that allows it to be
switched quickly to any other mode
AXRADIO_MODE_
DEEPSLEEP
The radio is in deep sleep mode; this mode has the lowest possible
power consumption, but may take some time to leave
AXRADIO_MODE_
CW_TRANSMIT
The radio is setup for CW (constant carrier wave) transmit (used
for basic tests)
AXRADIO_MODE_
ASYNC_TRANSMIT
The radio is set up for asynchronous transmission. After a call to
axradio_transmit, the transmitter is switched on and the packet is
sent, afterwards the transmitter is switched off again.
AXRADIO_MODE_
WOR_TRANSMIT
Same as AXRADIO_MODE_ASYNC_TRANSMIT, but starts
transmission with a wakeup preamble
AXRADIO_MODE_
ACK_TRANSMIT
The radio is set up for asynchronous transmission. After a call to
axradio_transmit, the transmitter is switched on and the packet is
sent, afterwards the radio waits for an acknowledge from the slave.
If no acknowledge is received within a configured timespan, the
packet is (optionally) retransmitted.
AXRADIO_MODE_
Same as AXRADIO_MODE_ACK_TRANSMIT, but starts transmission
WOR_ACK_TRANSMIT with a wakeup preamble
AXRADIO_MODE_
ASYNC_RECEIVE
The radio is setup for continuous asynchronous receive.
AXRADIO_MODE_
WOR_RECEIVE
The radio is setup for wake-on-radio receive.
AXRADIO_MODE_
ACK_RECEIVE
The radio is setup for continuous asynchronous receive. After a
packet is received, an acknowledge packet is sent back.
AXRADIO_MODE_
WOR_ACK_RECEIVE
The radio is setup for wake-on-radio receive. After a packet is
received, an acknowledge packet is sent back.
www.onsemi.com
AND9360/D
Constants
Mode
Description
AXRADIO_MODE_
STREAM_TRANSMIT
The radio is setup for streaming transmit (used for basic tests)
AXRADIO_MODE_
STREAM_TRANSMIT_
UNENC
The radio is setup for unencoded streaming transmit (used for
basic tests)
AXRADIO_MODE_
STREAM_TRANSMIT_
SCRAM
The radio is setup for scrambled streaming transmit (used for basic
tests)
AXRADIO_MODE_
STREAM_RECEIVE
The radio is setup for streaming receive (used for basic tests)
AXRADIO_MODE_
STREAM_RECEIVE_
UNENC
The radio is setup for unencoded streaming receive (used for basic
tests)
AXRADIO_MODE_
STREAM_RECEIVE_
SCRAM
The radio is setup for scrambled streaming receive (used for basic
tests)
AXRADIO_MODE_
SYNC_MASTER
The radio is setup as synchronous master.
AXRADIO_MODE_
SYNC_ACK_MASTER
The radio is setup as synchronous master. The master expects an
acknowledge from the slave, and reports the acknowledge or the
absence of an acknowledge to the caller.
AXRADIO_MODE_
SYNC_SLAVE
The radio is setup as synchronous slave.
AXRADIO_MODE_
SYNC_ACK_SLAVE
The radio is setup as synchronous slave. The slave sends an
acknowledge whenever a packet is received.
3.2. E R R O R C O D E S
Error Code
Description
AXRADIO_ERR_
NOERROR
No error occured, operation completed successfully
AXRADIO_ERR_
NOTSUPPORTED
The operation is not supported
www.onsemi.com
AND9360/D
5
6
Constants
Error Code
Description
AXRADIO_ERR_
BUSY
The operation could not be completed because the radio was busy
AXRADIO_ERR_
TIMEOUT
The operation timed out (eg. the maximum number of
retransmission exceeded)
AXRADIO_ERR_
INVALID
The operation failed because of an invalid parameter
AXRADIO_ERR_
NOCHIP
No radio chip was found
AXRADIO_ERR_
RANGING
The frequency could not be ranged
AXRADIO_ERR_
LOCKLOST
PLL lock was lost
AXRADIO_ERR_
RETRANSMISSION
This packet is a retransmission (due to no acknowledge received)
AXRADIO_ERR_
RESYNC
The synchronous slave restarts resynchronization.
AXRADIO_ERR_
RESYNCTIMEOUT
The synchronous slave pauses resynchronization.
AXRADIO_ERR_
RECEIVESTART
The synchronous slave powers up the receiver.
3.3. S T A T U S C H A N G E C O D E S
Status Change Code
Description
AXRADIO_STAT_
RECEIVE
Receive Packet arrived
AXRADIO_STAT_
TRANSMITSTART
Transmitter start notification
AXRADIO_STAT_
TRANSMITDATA
Transmitter new data needed notification for streaming transmit
modes
AXRADIO_STAT_
TRANSMITEND
Transmitter end notification
AXRADIO_STAT_
RECEIVESFD
Receiver SFD detected notification
AXRADIO_STAT_
Channel state update
www.onsemi.com
AND9360/D
Constants
Status Change Code
Description
CHANNELSTATE
In the acknowledge modes, at the start of transmission, TRANSMITSTART is called either
with NOERROR or RETRANSMISSION, depending on whether it is the first or subsequent
transmission of a packet. At the end of the packet transmission, TRANSMITEND is called
with BUSY. When an acknowledge is received, TRANSMITEND is called again with
NOERROR. If no acknowledge is received after a timeout, and the number of
retransmissions is used up, TRANSMITEND is called with TIMEOUT.
The synchronous master first calls TRANSMITDATA approximately 1ms before turning on
the transmitter. This call may be used to prepare the transmit packet and call
axradio_transmit.
4. F U N C T I O N S
4.1.
U I N T 8_ T A X R A D I O _ I N I T ( V O I D )
Initialize the driver and the chip. This routine must be called before any other axradio
routine is called. Returns one of the following error codes:
Error Code
Description
AXRADIO_ERR_
NOERROR
No error occured.
AXRADIO_ERR_
NOCHIP
No radio chip was found
AXRADIO_ERR_
RANGING
The frequency could not be ranged
4.2.
U I N T 8_ T A X R A D I O _ C A N S L E E P ( V O I D )
This function returns one if the processor can go to sleep without adverse effects, or zero if
the required interrupt latency could not be fulfilled when going to sleep.
This function should be used as follows:
wtimer_runcallbacks();
www.onsemi.com
AND9360/D
7
8
Functions
uint8_t flags = WTFLAG_CANSTANDBY;
if (axradio_cansleep())
flags |= WTFLAG_CANSLEEP;
wtimer_idle(flags);
4.3.
U I N T 8_ T A X R A D I O _ S E T _ M O D E ( U I N T 8_ T M O D E )
This function sets the mode of the radio. Supply one of the AXRADIO_MODE_* constants.
Not all modes may be supported, depending on the configuration set in AXRadioLab.
It returns one of the following error codes:
Error Code
Description
AXRADIO_ERR_
NOERROR
No error occured, operation completed successfully
AXRADIO_ERR_
NOTSUPPORTED
The operation is not supported
AXRADIO_ERR_
NOCHIP
No radio chip was found
AXRADIO_ERR_
RANGING
The frequency could not be ranged
4.4.
U I N T 8_ T A X R A D I O _ G E T _ M O D E ( V O I D )
This function returns the current chip operating mode. See the AXRADIO_MODE_*
constants.
4.5.
U I N T 8_ T A X R A D I O _ S E T _ C H A N N E L ( U I N T 8_ T C H N U M )
This function sets the channel number to be used. The mapping between channel number
and frequency is configured in AXRadioLab. This function returns one of the following error
codes:
Error Code
Description
AXRADIO_ERR_
No error occured, operation completed successfully
www.onsemi.com
AND9360/D
Functions
Error Code
Description
NOERROR
AXRADIO_ERR_
BUSY
The operation could not be completed because the radio was busy
AXRADIO_ERR_
INVALID
The operation failed because of an invalid parameter
AXRADIO_ERR_
RANGING
The frequency could not be ranged
4.6.
U I N T 8_ T A X R A D I O _ G E T _ C H A N N E L ( V O I D )
This function returns the currently used channel number.
4.7.
U I N T 8_ T A X R A D I O _ G E T _ P L L R A N G E ( V O I D )
U I N T 8_ T A X R A D I O _ G E T _ P L L R A N G E _ T X ( V O I D )
These functions return the current PLL ranges for the currently set frequency. This is mainly
for debugging.
4.8.
VOID AXRADIO_SET_LOCAL_ADDRESS( CONST STRUCT AXRADIO_ADDRESS_MASK
*ADDR)
This function sets the MAC address of the local radio node. The length of a MAC address is
configured by AXRadioLab.
The axradio_address_mask structure has the following definition:
struct axradio_address_mask {
uint8_t addr[4];
uint8_t mask[4];
};
4.9.
VOID AXRADIO_GET_LOCAL_ADDRESS(STRUCT AXRADIO_ADDRESS_MASK
*ADDR)
This function returns the currently configured local radio node MAC address. A pointer to a
memory space where the address can be stored into must be provided.
www.onsemi.com
AND9360/D
9
10
Functions
4.10. U I N T 8_ T
A X R A D I O _ S E T _ F R E Q O F F S E T ( I N T 32_ T O F F S )
Axradio allows the user to shift the transceiver somewhat from the channel center
frequency. This can be useful in a master-slave setup, where the slaves adjust their
frequency upon reception from the master (axradio measures the frequency offset of every
packet received), to compensate for drifting crystals.
This routine sets the frequency offset from the channel center frequency that should be
used. The offset remains when channels are switched.
The unit is a driver internal one. It can be converted to and from Hz using the
axradio_conv_freq_* routines.
4.11. I N T 32_ T
AXRADIO_GET_FREQOFFSET( VOID)
This routine returns the current frequency offset.
4.12. I N T 32_ T
A X R A D I O _ C O N V _ F R E Q _ T O H Z ( I N T 32_ T F )
This routine converts internal unit frequency offsets to Hz.
4.13. I N T 32_ T
A X R A D I O _ C O N V _ F R E Q _ F R O M H Z ( I N T 32_ T F )
This routine converts frequency offsets in Hz into internal units for frequency offset.
4.14. I N T 32_ T
A X R A D I O _ C O N V _ T I M E I N T E R V A L _ T O T I M E R 0( I N T 32_ T D T )
This function converts a time interval, such as a difference of two status callback st->time
values, into wakeup timer 0 units.
4.15. U I N T 32_ T
A X R A D I O _ C O N V _ T I M E _ T O T I M E R 0( U I N T 32_ T D T )
This function converts an absolute time, such as a status callback st->time value, from
internal units to wakeup timer 0 units. Note that status callback st->time values are
generally only valid during the status callback, as the relationship between the internal
www.onsemi.com
AND9360/D
Functions
timer and the wakeup timer 0 may change, for example when the radio chip is powered
down.
4.16. U I N T 8_ T A X R A D I O _ T R A N S M I T ( C O N S T
U I N T 8_ T * P K T , U I N T 16_ T L E N )
STRUCT AXRADIO_ADDRESS
*ADDR,
CONST
Calling this function transfers the user packet data pointed to by pkt and having length len
to axradio for transmission. Only one packet may be in the process of being transmitted at
any time. If a second packet transmission is attempted, a busy error is returned.
The semantics of this routine slightly differs depending on whether the driver is in an
asynchronous or a synchronous mode.
In an asynchronous mode, calling this routine queues the packet and immediately starts
transmission.
In a synchronous mode, the data is stored for transmission in the next time slot. If this
routine is called a second time before the next time slot, the old data is replaced by the
data passed in the second call. This may be used to record default data early in the cycle,
and possibly update the data if something happens.
The addr argument specifies the address of the remote station this packet is destined to.
The axradio_address structure has the following definition:
struct axradio_address {
uint8_t addr[4];
};
4.17. U I N T 8_ T A X R A D I O _ A G C _ F R E E Z E ( V O I D )
U I N T 8_ T A X R A D I O _ A G C _ T H A W ( V O I D )
axradio_agc_freeze/axradio_agc_thaw may be used during the streaming receive modes to
freeze or thaw the automatic gain control.
www.onsemi.com
AND9360/D
11
12
Functions
4.18. V O I D
AXRADIO_STATUSCHANGE(CONST
__ X D A T A
STRUCT AXRADIO_STATUS
*ST)
This function must be provided by the user code. It is called by axradio whenever an event
that needs to be notified happens.
struct axradio_status {
uint8_t status; // one of the AXRADIO_STAT_* constants
uint8_t error; // one of the AXRADIO_ERR_* constants
uint32_t time; // timestamp of the event
//
union {
// status == AXRADIO_STAT_RECEIVE
struct {
struct {
int8_t rssi; // RSSI, dBm
int32_t offset; // frequency offset, internal units
} phy;
struct {
uint8_t remoteaddr[4];
uint8_t localaddr[4];
const __xdata uint8_t *raw;
} mac;
const __xdata uint8_t *pktdata;
uint16_t pktlen;
} rx;
// status == AXRADIO_STAT_CHANNELSTATE
struct {
int8_t rssi; // RSSI, dBm
uint8_t busy; // 1=over the LBT threshold
} cs;
} u;
};
5. S T A T I C C O N F I G U R A T I O N I T E M S
These static configuration constants are computed by AX-RadioLab.
www.onsemi.com
AND9360/D
Static Configuration Items
5.1.
EXTERN CONST
__ C O D E
U I N T 8_ T A X R A D I O _ M A C L E N ;
This constant contains the length of the MAC header in front of the user packet data.
5.2.
EXTERN CONST
__ C O D E
U I N T 8_ T A X R A D I O _ A D D R L E N ;
This constant contains the length of a MAC address, and may be in the range of 1–4.
6. E X A M P L E
USAGE CODE
This section lists simplified code to illustrate the usage of the API.
6.1. S I M P L E A S Y N C H R O N O U S
This example shows the skeleton for the simplest possible asynchronous transmitter to
receiver case.
6.1.1.
TRANSMITTER
#include "ax8052.h"
#include "libmftypes.h"
#include "libmfwtimer.h"
#include "libmfflash.h"
#include "libmfradio.h"
#include "axradio.h"
static const __code struct axradio_address_mask localaddr = {
{ 0x12, 0x34, 0x56, 0x78 },
{ 0xFF, 0xFF, 0xFF, 0xFF }
};
static const __code struct axradio_address remoteaddr = {
www.onsemi.com
AND9360/D
13
14
Example usage code
{ 0xCA, 0xFE, 0xBA, 0xBE }
};
void axradio_statuschange(const __xdata struct axradio_status *st)
{
}
uint8_t _sdcc_external_startup(void)
{
// initialize GPIO, peripherals
if (PCON & 0x40)
return 1;
return 0;
}
#if defined(SDCC)
extern uint8_t _start__stack[];
#endif
void main (void)
{
#if !defined(SDCC)
_sdcc_external_startup();
#else
__asm
G$_start__stack$0$0 = __start__stack
.globl G$_start__stack$0$0
__endasm;
#endif
flash_apply_calibration(); // check for non-existing calibration
CLKCON = 0x00;
www.onsemi.com
AND9360/D
Example usage code
wtimer_init(CLKSRC_LPOSC, 1, CLKSRC_FRCOSC, 7);
EA = 1;
if (!(PCON & 0x40)) {
axradio_init(); // check for error
axradio_set_local_addr(&localaddr);
} else {
AX5051_commsleepexit();
}
for (;;) {
uint8_t flg;
if (key is pressed) {
__xdata uint8_t userpkt[..];
// fill userpkt
axradio_transmit(&remoteaddr, userpkt, sizeof(userpkt));
}
wtimer_runcallbacks();
flg = WTFLAG_CANSTANDBY;
if (axradio_cansleep())
flg |= WTFLAG_CANSLEEP;
wtimer_idle(flg);
}
}
6.1.2.
RECEIVER
#include "ax8052.h"
#include "libmftypes.h"
#include "libmfwtimer.h"
www.onsemi.com
AND9360/D
15
16
Example usage code
#include "libmfflash.h"
#include "libmfradio.h"
#include "axradio.h"
static const __code struct axradio_address_mask localaddr = {
{ 0xCA, 0xFE, 0xBA, 0xBE },
{ 0xFF, 0xFF, 0xFF, 0xFF }
};
void axradio_statuschange(const __xdata struct axradio_status *st)
{
switch (st->status) {
case AXRADIO_STAT_RECEIVE:
// check st->error
// display st->u.rx.pktdata / st->u.rx.pktlen
break;
default:
break;
}
}
uint8_t _sdcc_external_startup(void)
{
// initialize GPIO, peripherals
if (PCON & 0x40)
return 1;
return 0;
}
#if defined(SDCC)
extern uint8_t _start__stack[];
www.onsemi.com
AND9360/D
Example usage code
#endif
void main (void)
{
#if !defined(SDCC)
_sdcc_external_startup();
#else
__asm
G$_start__stack$0$0 = __start__stack
.globl G$_start__stack$0$0
__endasm;
#endif
flash_apply_calibration(); // check for non-existing calibration
CLKCON = 0x00;
wtimer_init(CLKSRC_LPOSC, 1, CLKSRC_FRCOSC, 7);
EA = 1;
if (!(PCON & 0x40)) {
axradio_init(); // check for error
axradio_set_local_addr(&localaddr);
} else {
AX5051_commsleepexit();
}
for (;;) {
uint8_t flg;
wtimer_runcallbacks();
flg = WTFLAG_CANSTANDBY;
if (axradio_cansleep())
flg |= WTFLAG_CANSLEEP;
www.onsemi.com
AND9360/D
17
18
Example usage code
wtimer_idle(flg);
}
}
7. F I L E S
This section lists the files that need to be included in an AXRadio project and what their
purpose is.
File
Description
axradio.h
AXRadio API declaration
easyax5043.h
AXRadio AX5043 private header – AX5043 only
easyax5043.c
AXRadio AX5043 main code – AX5043 only
easyax5051.h
AXRadio AX5051 private header – AX5051 only
easyax5051.c
AXRadio AX5051 main code – AX5051 only
config.c
Parameters generated by AXRadioLab
www.onsemi.com
AND9360/D
19
ON Semiconductor and the ON logo are registered trademarks of Semiconductor Components Industries, LLC (SCILLC) or its subsidiaries in the United States and/or other
countries. SCILLC owns the rights to a number of patents, trademarks, copyrights, trade secrets, and other intellectual property. A listing of SCILLC’s product/patent coverage
may be accessed at www.onsemi.com/site/pdf/Patent-Marking.pdf. SCILLC reserves the right to make changes without further notice to any products herein. SCILLC makes
no warranty, representation or guarantee regarding the suitability of its products for any particular purpose, nor does SCILLC assume any liability arising out of the
application or use of any product or circuit, and specifically disclaims any and all liability, including without limitation special, consequential or incidental damages. “Typical”
parameters which may be provided in SCILLC data sheets and/or specifications can and do vary in different applications and actual performance may vary over time. All
operating parameters, including “Typicals” must be validated for each customer application by customer’s technical experts. SCILLC does not convey any license under its
patent rights nor the rights of others. SCILLC products are not designed, intended, or authorized for use as components in systems intended for surgical implant into the
body, or other applications intended to support or sustain life, or for any other application in which the failure of the SCILLC product could create a situation where personal
injury or death may occur. Should Buyer purchase or use SCILLC products for any such unintended or unauthorized application, Buyer shall indemnify and hold SCILLC and
its officers, employees, subsidiaries, affiliates, and distributors harmless against all claims, costs, damages, and expenses, and reasonable attorney fees arising out of,
directly or indirectly, any claim of personal injury or death associated with such unintended or unauthorized use, even if such claim alleges that SCILLC was negligent
regarding the design or manufacture of the part. SCILLC is an Equal Opportunity/Affirmative Action Employer. This literature is subject to all applicable copyright laws and is
not for resale in any manner.
PUBLICATION ORDERING INFORMATION
LITERATURE FULFILLMENT:
Literature Distribution Center for ON Semiconductor
19521 E. 32nd Pkwy, Aurora, Colorado 80011 USA
Phone: 303-675-2175 or 800-344-3860 Toll Free USA/Canada
Fax: 303-675-2176 or 800-344-3867 Toll Free USA/Canada
Email: [email protected]
N. American Technical Support: 800-282-9855 Toll Free
USA/Canada.
Europe, Middle East and Africa Technical Support:
Phone: 421 33 790 2910
Japan Customer Focus Center
Phone: 81-3-5817-1050
www.onsemi.com
Order Literature: http://www.onsemi.com/orderlit
For additional information, please contact your local
Sales Representative
ON Semiconductor Website: www.onsemi.com
AND9360/D