Ash#

Use the Asynchronous Serial Host (ASH) Framework interfaces on a host microcontroller when it communicates with an Ember chip via EZSP-UART.

See ash-protocol.h for source code.

See ash-common.h for source code.

Variables#

bool

set false to start decoding a new frame

uint16_t

rec'd ack timer (msecs)

uint16_t

rec'd ack timer period (msecs)

uint8_t

not ready timer (16 msec units)

Functions#

uint8_t
ashEncodeByte(uint8_t len, uint8_t byte, uint8_t *offset)

Builds an ASH frame.

EzspStatus
ashDecodeByte(uint8_t byte, uint8_t *out, uint8_t *outLen)

Decodes and validates an ASH frame.

uint8_t
ashRandomizeArray(uint8_t seed, uint8_t *buf, uint8_t len)

Randomizes array contents by XORing with an 8-bit pseudo random sequence.

void

Sets ashAckTimer to the specified period and starts it running.

bool

Indicates whether or not ashAckTimer has expired.

void
ashAdjustAckPeriod(bool expired)

Adapts the acknowledgement timer period to the observed ACK delay.

void

Starts the Not Ready timer.

bool

Tests whether the Not Ready timer has expired or has stopped.

Macros#

#define

Stops and clears ashAckTimer.

#define

Indicates whether or not ashAckTimer is currently running.

#define

Indicates whether or not ashAckTimer is currently running.

#define

Sets the acknowledgement timer period (in msec) and stops the timer.

#define

Returns the acknowledgement timer period (in msec).

#define

Sets the acknowledgement timer period (in msec), and starts the timer running.

#define

log2 of msecs per NR timer unit

#define

Stops the Not Ready timer.

#define

Indicates whether or not ashNrTimer is currently running.

#define

protocol version

#define

frame delimiter

#define
ASH_ESC 0x7D

byte stuffing escape byte

#define
ASH_XON 0x11

flow control byte - means resume transmission

#define

flow control byte - means suspend transmission

#define
ASH_SUB 0x18

replaces bytes w framing, overrun or overflow errors

#define
ASH_CAN 0x1A

frame cancel byte

#define

wake signal byte (also means NCP data pending)

#define

XOR mask used in byte stuffing.

#define
ASH_MIN_DATA_FIELD_LEN EZSP_MIN_FRAME_LENGTH

ash min data field len

#define
ASH_MAX_DATA_FIELD_LEN EZSP_MAX_FRAME_LENGTH

ash max data field len

#define
ASH_MIN_DATA_FRAME_LEN (ASH_MIN_DATA_FIELD_LEN + 1)

with control

#define

control plus data field, but not CRC

#define
ASH_MAX_FRAME_LEN (ASH_MAX_DATA_FIELD_LEN + 1)

ash max frame len

#define

ash crc len

#define
ASH_MIN_FRAME_WITH_CRC_LEN (ASH_MIN_FRAME_LEN + ASH_CRC_LEN)

ash min frame with crc len

#define
ASH_MAX_FRAME_WITH_CRC_LEN (ASH_MAX_FRAME_LEN + ASH_CRC_LEN)

ash max frame with crc len

#define

longest non-data frame received

#define

longest non-data frame sent

#define

longest non-data frame received

#define

longest non-data frame sent

#define

ash dframe mask

#define

ash control data

#define

ash shframe mask

#define

ash control ack

#define

ash control nak

#define

ash control rst

#define

ash control rstack

#define

ash control error

#define

acknowledge frame number

#define

ash acknum bit

#define

retransmitted frame flag

#define

ash rflag bit

#define

receiver not ready flag

#define

ash nflag bit

#define

flag reserved for future use

#define

ash pflag bit

#define

DATA frame number.

#define

ash frmnum bit

#define

ash get rflag(ctl)

#define

ash get nflag(ctl)

#define

ash get frmnum(ctl)

#define

ash get acknum(ctl)

#define
ASH_FRAME_LEN_DATA_MIN (ASH_MIN_DATA_FIELD_LEN + 1)

ash frame len data min

#define
#define
#define
#define

control, version, reset reason

#define

control, version, error

#define
MOD8 (n)

mask to frame number modulus

#define
INC8 (n)

increment in frame number modulus

#define
WITHIN_RANGE (lo, n, hi)

within range lo and hi

Variable Documentation#

ashDecodeInProgress#

bool ashDecodeInProgress

set false to start decoding a new frame


Definition at line 193 of file platform/service/legacy_common_ash/inc/ash-common.h

ashAckTimer#

uint16_t ashAckTimer

rec'd ack timer (msecs)


Definition at line 196 of file platform/service/legacy_common_ash/inc/ash-common.h

ashAckPeriod#

uint16_t ashAckPeriod

rec'd ack timer period (msecs)


Definition at line 197 of file platform/service/legacy_common_ash/inc/ash-common.h

ashNrTimer#

uint8_t ashNrTimer

not ready timer (16 msec units)


Definition at line 198 of file platform/service/legacy_common_ash/inc/ash-common.h

Function Documentation#

ashEncodeByte#

uint8_t ashEncodeByte (uint8_t len, uint8_t byte, uint8_t * offset)

Builds an ASH frame.

Parameters
N/Alen

new frame flag / length of the frame to be encoded. A non-zero value begins a new frame, so all subsequent calls must use zero. The length includes control byte and data field, but not the flag or crc. This function does not validate the length.

N/Abyte

the next byte of data to add to the frame. Note that in general the same byte of data may have to be passed more than once as escape bytes, the CRC and the end flag byte are output.

N/Aoffset

pointer to the offset of the next input byte. (If the frame data is the array data[], the next byte would be data[offset].) Is set to 0 when starting a new frame (ie, len is non-zero). Is set to 0xFF when the last byte of the frame is returned.

Byte stuffs the control and data fields as required, computes and appends the CRC and adds the ending flag byte. Called with the next byte to encode, this function may return several output bytes before it's ready for the next byte.

Returns

  • next encoded output byte in frame.


Definition at line 53 of file platform/service/legacy_common_ash/inc/ash-common.h

ashDecodeByte#

EzspStatus ashDecodeByte (uint8_t byte, uint8_t * out, uint8_t * outLen)

Decodes and validates an ASH frame.

Parameters
N/Abyte

the next byte of data to add to the frame

N/Aout

pointer to where to write an output byte

N/AoutLen

number of bytes output so far

Data is passed to it one byte at a time. Decodes byte stuffing, checks crc, finds the end flag and (if enabled) terminates the frame early on CAN or SUB bytes. The number of bytes output will not exceed the max valid frame length, which does not include the flag or the crc.

Returns

  • status of frame decoding

    • ::EZSP_SUCCESS

    • ::EZSP_ASH_IN_PROGRESS

    • ::EZSP_ASH_CANCELLED

    • ::EZSP_ASH_BAD_CRC

    • ::EZSP_ASH_COMM_ERROR

    • ::EZSP_ASH_TOO_SHORT

    • ::EZSP_ASH_TOO_LONG


Definition at line 76 of file platform/service/legacy_common_ash/inc/ash-common.h

ashRandomizeArray#

uint8_t ashRandomizeArray (uint8_t seed, uint8_t * buf, uint8_t len)

Randomizes array contents by XORing with an 8-bit pseudo random sequence.

Parameters
N/Aseed

zero initializes the random sequence a non-zero value continues from a previous invocation

N/Abuf

pointer to the array whose contents will be randomized

N/Alen

number of bytes in the array to modify

This reduces the likelihood that byte-stuffing will greatly increase the size of the payload. (This could happen if a DATA frame contained repeated instances of the same reserved byte value.)

Returns

  • last value of the sequence. If a buffer is processed in two or more chunks, as with linked buffers, this value should be passed back as the value of the seed argument


Definition at line 95 of file platform/service/legacy_common_ash/inc/ash-common.h

ashStartAckTimer#

void ashStartAckTimer (void )

Sets ashAckTimer to the specified period and starts it running.

Parameters
N/A

Definition at line 101 of file platform/service/legacy_common_ash/inc/ash-common.h

ashAckTimerHasExpired#

bool ashAckTimerHasExpired (void )

Indicates whether or not ashAckTimer has expired.

Parameters
N/A

If the timer is stopped then it is not expired.

Returns

  • bool


Definition at line 127 of file platform/service/legacy_common_ash/inc/ash-common.h

ashAdjustAckPeriod#

void ashAdjustAckPeriod (bool expired)

Adapts the acknowledgement timer period to the observed ACK delay.

Parameters
N/Aexpired

true if timer has expired

If the timer is not running, it does nothing. If the timer has expired, the timeourt period is doubled. If the timer has not expired, the elapsed time is fed into simple IIR filter: T[n+1] = (7*T[n] + elapsedTime) / 8 The timeout period, ashAckPeriod, is limited such that: ASH_xxx_TIME_DATA_MIN <= ashAckPeriod <= ASH_xxx_TIME_DATA_MAX, where xxx is either HOST or NCP.

The acknowledgement timer is always stopped by this function.


Definition at line 145 of file platform/service/legacy_common_ash/inc/ash-common.h

ashStartNrTimer#

void ashStartNrTimer (void )

Starts the Not Ready timer.

Parameters
N/A

On the host, this times nFlag refreshing when the host doesn't have room for callbacks for a prolonged period.

On the NCP, if this times out the NCP resumes sending callbacks.


Definition at line 175 of file platform/service/legacy_common_ash/inc/ash-common.h

ashNrTimerHasExpired#

bool ashNrTimerHasExpired (void )

Tests whether the Not Ready timer has expired or has stopped.

Parameters
N/A

If expired, it is stopped.

Returns

  • true if the Not Ready timer has expired or stopped


Definition at line 186 of file platform/service/legacy_common_ash/inc/ash-common.h

Macro Definition Documentation#

ashStopAckTimer#

#define ashStopAckTimer
Value:
(void)

Stops and clears ashAckTimer.


Definition at line 108 of file platform/service/legacy_common_ash/inc/ash-common.h

ashAckTimerIsRunning#

#define ashAckTimerIsRunning
Value:
()

Indicates whether or not ashAckTimer is currently running.

The timer may be running even if expired.


Definition at line 114 of file platform/service/legacy_common_ash/inc/ash-common.h

ashAckTimerIsNotRunning#

#define ashAckTimerIsNotRunning
Value:
()

Indicates whether or not ashAckTimer is currently running.

The timer may be running even if expired.


Definition at line 120 of file platform/service/legacy_common_ash/inc/ash-common.h

ashSetAckPeriod#

#define ashSetAckPeriod
Value:
(msec)

Sets the acknowledgement timer period (in msec) and stops the timer.


Definition at line 151 of file platform/service/legacy_common_ash/inc/ash-common.h

ashGetAckPeriod#

#define ashGetAckPeriod
Value:
()

Returns the acknowledgement timer period (in msec).


Definition at line 157 of file platform/service/legacy_common_ash/inc/ash-common.h

ashSetAndStartAckTimer#

#define ashSetAndStartAckTimer
Value:
(msec)

Sets the acknowledgement timer period (in msec), and starts the timer running.


Definition at line 162 of file platform/service/legacy_common_ash/inc/ash-common.h

ASH_NR_TIMER_BIT#

#define ASH_NR_TIMER_BIT
Value:
4

log2 of msecs per NR timer unit


Definition at line 166 of file platform/service/legacy_common_ash/inc/ash-common.h

ashStopNrTimer#

#define ashStopNrTimer
Value:
()

Stops the Not Ready timer.


Definition at line 179 of file platform/service/legacy_common_ash/inc/ash-common.h

ashNrTimerIsNotRunning#

#define ashNrTimerIsNotRunning
Value:
()

Indicates whether or not ashNrTimer is currently running.


Definition at line 191 of file platform/service/legacy_common_ash/inc/ash-common.h

ASH_VERSION#

#define ASH_VERSION
Value:
2

protocol version


Definition at line 35 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_FLAG#

#define ASH_FLAG
Value:
0x7E

frame delimiter


Definition at line 39 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_ESC#

#define ASH_ESC
Value:
0x7D

byte stuffing escape byte


Definition at line 40 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_XON#

#define ASH_XON
Value:
0x11

flow control byte - means resume transmission


Definition at line 41 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_XOFF#

#define ASH_XOFF
Value:
0x13

flow control byte - means suspend transmission


Definition at line 42 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_SUB#

#define ASH_SUB
Value:
0x18

replaces bytes w framing, overrun or overflow errors


Definition at line 43 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_CAN#

#define ASH_CAN
Value:
0x1A

frame cancel byte


Definition at line 44 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_WAKE#

#define ASH_WAKE
Value:
0xFF

wake signal byte (also means NCP data pending)


Definition at line 48 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_FLIP#

#define ASH_FLIP
Value:
0x20

XOR mask used in byte stuffing.


Definition at line 51 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_MIN_DATA_FIELD_LEN#

#define ASH_MIN_DATA_FIELD_LEN
Value:
EZSP_MIN_FRAME_LENGTH

ash min data field len


Definition at line 55 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_MAX_DATA_FIELD_LEN#

#define ASH_MAX_DATA_FIELD_LEN
Value:
EZSP_MAX_FRAME_LENGTH

ash max data field len


Definition at line 56 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_MIN_DATA_FRAME_LEN#

#define ASH_MIN_DATA_FRAME_LEN
Value:
(ASH_MIN_DATA_FIELD_LEN + 1)

with control


Definition at line 57 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_MIN_FRAME_LEN#

#define ASH_MIN_FRAME_LEN
Value:
1

control plus data field, but not CRC


Definition at line 58 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_MAX_FRAME_LEN#

#define ASH_MAX_FRAME_LEN
Value:
(ASH_MAX_DATA_FIELD_LEN + 1)

ash max frame len


Definition at line 59 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_CRC_LEN#

#define ASH_CRC_LEN
Value:
2

ash crc len


Definition at line 60 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_MIN_FRAME_WITH_CRC_LEN#

#define ASH_MIN_FRAME_WITH_CRC_LEN
Value:
(ASH_MIN_FRAME_LEN + ASH_CRC_LEN)

ash min frame with crc len


Definition at line 61 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_MAX_FRAME_WITH_CRC_LEN#

#define ASH_MAX_FRAME_WITH_CRC_LEN
Value:
(ASH_MAX_FRAME_LEN + ASH_CRC_LEN)

ash max frame with crc len


Definition at line 62 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_NCP_SHFRAME_RX_LEN#

#define ASH_NCP_SHFRAME_RX_LEN
Value:
2

longest non-data frame received


Definition at line 65 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_NCP_SHFRAME_TX_LEN#

#define ASH_NCP_SHFRAME_TX_LEN
Value:
3

longest non-data frame sent


Definition at line 66 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_HOST_SHFRAME_RX_LEN#

#define ASH_HOST_SHFRAME_RX_LEN
Value:
3

longest non-data frame received


Definition at line 67 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_HOST_SHFRAME_TX_LEN#

#define ASH_HOST_SHFRAME_TX_LEN
Value:
2

longest non-data frame sent


Definition at line 68 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_DFRAME_MASK#

#define ASH_DFRAME_MASK
Value:
0x80

ash dframe mask


Definition at line 89 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_CONTROL_DATA#

#define ASH_CONTROL_DATA
Value:
0x00

ash control data


Definition at line 90 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_SHFRAME_MASK#

#define ASH_SHFRAME_MASK
Value:
0xE0

ash shframe mask


Definition at line 92 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_CONTROL_ACK#

#define ASH_CONTROL_ACK
Value:
0x80

ash control ack


Definition at line 93 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_CONTROL_NAK#

#define ASH_CONTROL_NAK
Value:
0xA0

ash control nak


Definition at line 94 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_CONTROL_RST#

#define ASH_CONTROL_RST
Value:
0xC0

ash control rst


Definition at line 95 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_CONTROL_RSTACK#

#define ASH_CONTROL_RSTACK
Value:
0xC1

ash control rstack


Definition at line 96 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_CONTROL_ERROR#

#define ASH_CONTROL_ERROR
Value:
0xC2

ash control error


Definition at line 97 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_ACKNUM_MASK#

#define ASH_ACKNUM_MASK
Value:
0x07

acknowledge frame number


Definition at line 99 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_ACKNUM_BIT#

#define ASH_ACKNUM_BIT
Value:
0

ash acknum bit


Definition at line 100 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_RFLAG_MASK#

#define ASH_RFLAG_MASK
Value:
0x08

retransmitted frame flag


Definition at line 101 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_RFLAG_BIT#

#define ASH_RFLAG_BIT
Value:
3

ash rflag bit


Definition at line 102 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_NFLAG_MASK#

#define ASH_NFLAG_MASK
Value:
0x08

receiver not ready flag


Definition at line 103 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_NFLAG_BIT#

#define ASH_NFLAG_BIT
Value:
3

ash nflag bit


Definition at line 104 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_PFLAG_MASK#

#define ASH_PFLAG_MASK
Value:
0x10

flag reserved for future use


Definition at line 105 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_PFLAG_BIT#

#define ASH_PFLAG_BIT
Value:
4

ash pflag bit


Definition at line 106 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_FRMNUM_MASK#

#define ASH_FRMNUM_MASK
Value:
0x70

DATA frame number.


Definition at line 107 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_FRMNUM_BIT#

#define ASH_FRMNUM_BIT
Value:
4

ash frmnum bit


Definition at line 108 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_GET_RFLAG#

#define ASH_GET_RFLAG
Value:
(ctl)

ash get rflag(ctl)


Definition at line 109 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_GET_NFLAG#

#define ASH_GET_NFLAG
Value:
(ctl)

ash get nflag(ctl)


Definition at line 110 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_GET_FRMNUM#

#define ASH_GET_FRMNUM
Value:
(ctl)

ash get frmnum(ctl)


Definition at line 111 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_GET_ACKNUM#

#define ASH_GET_ACKNUM
Value:
(ctl)

ash get acknum(ctl)


Definition at line 112 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_FRAME_LEN_DATA_MIN#

#define ASH_FRAME_LEN_DATA_MIN
Value:
(ASH_MIN_DATA_FIELD_LEN + 1)

ash frame len data min


Definition at line 116 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_FRAME_LEN_ACK#

#define ASH_FRAME_LEN_ACK
Value:
1

control


Definition at line 117 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_FRAME_LEN_NAK#

#define ASH_FRAME_LEN_NAK
Value:
1

control


Definition at line 118 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_FRAME_LEN_RST#

#define ASH_FRAME_LEN_RST
Value:
1

control


Definition at line 119 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_FRAME_LEN_RSTACK#

#define ASH_FRAME_LEN_RSTACK
Value:
3

control, version, reset reason


Definition at line 120 of file platform/service/legacy_common_ash/inc/ash-protocol.h

ASH_FRAME_LEN_ERROR#

#define ASH_FRAME_LEN_ERROR
Value:
3

control, version, error


Definition at line 121 of file platform/service/legacy_common_ash/inc/ash-protocol.h

MOD8#

#define MOD8
Value:
(n)

mask to frame number modulus


Definition at line 124 of file platform/service/legacy_common_ash/inc/ash-protocol.h

INC8#

#define INC8
Value:
(n)

increment in frame number modulus


Definition at line 125 of file platform/service/legacy_common_ash/inc/ash-protocol.h

WITHIN_RANGE#

#define WITHIN_RANGE
Value:
(lo, n, hi)

within range lo and hi


Definition at line 127 of file platform/service/legacy_common_ash/inc/ash-protocol.h