General ZPS Resources

The chapter describes the general API resources provided in the ZigBee PRO Stack (ZPS) software.

In this chapter:

The ZigBee Queue resources are detailed in Section 10.1.
The ZigBee Timer resources are detailed in Section 10.2.
The Critical Section and Mutex resources are detailed in Section 10.3.

Note: Amongst the general resources, functions are supplied to allow the extraction of payload data from received ZDP packets. These resources are not documented here but are provided in the header file appZdpExtractions.h.

ZigBee Queue Resources

The ZigBee Queue resources are concerned with creating and operating queues for passing messages from one task to another. These resources are provided in the header file ZQueue.h.

The ZigBee Queue functions are described in Section 10.1.1.
The ZigBee Queue structures are described in Section 10.1.2.

ZigBee queue functions

The ZigBee Queue functions are listed below.

Function page

Parent topic:ZigBee queue functions

ZQ_vQueueCreate

void ZQ_vQueueCreate(tszQueue *psQueueHandle,
                    const uint32 uiQueueLength,
                    const uint32 uiItemSize,
                    uint8 *pu8StartQueue);

Description

This function creates a message queue for use by the application or stack (message queues are described in Section 6.9.1). The size of the queue and the size of a message in the queue must be specified, as well as the location in memory where the queue should start. A unique handle must also be given to the queue, where this handle is a pointer to a tszQueuestructure that contains up-to-date information about the queue.

Parameters

psQueueHandle Handle of message queue - this is a pointer to a tszQueue structure (see Section 10.1.2.1).
uiQueueLength Size of the queue in terms of the number of messages that it can hold.
uiItemSize Size of a message in the queue, in bytes.
pu8StartQueue Pointer to the start of the message queue.

Parent topic:ZQ_vQueueCreate

Returns

None

Parent topic:ZQ_vQueueCreate

Parent topic:ZigBee queue functions

ZQ_bQueueSend

bool_t ZQ_bQueueSend(void *pvQueueHandle,
                    const void *pvItemToQueue);

Description

This function submits a message to the specified message queue. The return code indicates whether the message was successfully added to the queue.

Parent topic:ZQ_bQueueSend

Parameters

pvQueueHandle Handle of message queue
pvItemToQueue Pointer to the message to be added to the queue

Parent topic:ZQ_bQueueSend

Returns

Boolean indicating the outcome of the operation:

TRUE - message successfully added to the queue
FALSE - message not added to the queue

Parent topic:ZQ_bQueueSend

Parent topic:ZigBee queue functions

ZQ_bQueueReceive

ZQ_bQueueReceive(void *pvQueueHandle,
                void *pvItemFromQueue);

Description

This function obtains a message from the specified message queue. The return code indicates whether a message was successfully obtained from the queue.

Parent topic:ZQ_bQueueReceive

Parameters

pvQueueHandle: Handle of message queue
pvItemFromQueue: Pointer to memory location to receive the obtained message

Parent topic:ZQ_bQueueReceive

Returns

Boolean indicating the outcome of the operation:

TRUE - message successfully obtained from the queue.
FALSE - message not obtained from the queue.

Parent topic:ZQ_bQueueReceive

Parent topic:ZigBee queue functions

ZQ_bQueueIsEmpty

bool_t ZQ_bQueueIsEmpty(void *pvQueueHandle);

Description

This function checks whether the specified message queue is empty. The return code indicates whether the queue is empty.

Parent topic:ZQ_bQueueIsEmpty

Parameters

pvQueueHandle Handle of message queue

Parent topic:ZQ_bQueueIsEmpty

Returns

Boolean indicating the outcome of the operation:

TRUE - message queue is empty.
FALSE - message queue is not empty.

Parent topic:ZQ_bQueueIsEmpty

Parent topic:ZigBee queue functions

ZQ_u32QueueGetQueueSize

bool_t ZQ_bQueueIsEmpty(void *pvQueueHandle);

Description

This function obtains the capacity of the specified message queue. The return code indicates the size of the queue in terms of the number of messages that it can hold.

Parent topic:ZQ_u32QueueGetQueueSize

Parameters

pvQueueHandle Handle of message queue

Parent topic:ZQ_u32QueueGetQueueSize

Returns

The capacity of the queue in terms of the number of messages that it can hold.

Parent topic:ZQ_u32QueueGetQueueSize

Parent topic:ZigBee queue functions

ZQ_u32QueueGetQueueMessageWaiting

uint32 ZQ_u32QueueGetQueueMessageWaiting(
                    void *pu8QueueHandle);

Description

This function obtains the number of messages that are currently waiting in the specified message queue.

Parent topic:ZQ_u32QueueGetQueueMessageWaiting

Parameters

pvQueueHandle Handle of message queue

Parent topic:ZQ_u32QueueGetQueueMessageWaiting

Returns

Number of messages waiting in the queue

Parent topic:ZQ_u32QueueGetQueueMessageWaiting

Parent topic:ZigBee queue functions

Parent topic:ZigBee Queue Resources

ZigBee queue structures

tszQueue

The ZigBee queue structure tszQueueis shown below.

typedef struct
{
uint32 u32Length;
uint32 u32ItemSize;
uint32 u32MessageWaiting;
void *pvHead;
void *pvWriteTo;
void *pvReadFrom;
}tszQueue;

where:

u32Lengthis the size of the queue in terms of the number of messages that it can hold
u32ItemSizeis the size of a message, in bytes
u32MessageWaitingis the number of messages currently in the queue
pvHeadis a pointer to the beginning of the queue storage area
pvWriteTois a pointer to the next free place in the storage area where a new message can be written
pvReadFromis a pointer to the next message to be read from the storage area

Parent topic:ZigBee queue structures

Parent topic:ZigBee Queue Resources

Parent topic:General ZPS Resources

ZigBee Timer resources

The ZigBee Timer functions are concerned with initializing and operating software timers. These resources are provided in the header file ZTimer.h.

The ZigBee Timer functions are described in Section 10.2.1
The ZigBee Timer structures are described in Section 10.2.2

ZigBee Timer functions

The functions are listed below.

Function page

To use the software timers, the while loop of your application must include a call to the following function:

void ZTIMER\_vTask\(void\);

This allows the stack software to automatically update the ZTIMER\_tsTimer structure for each timer as the timer runs.

Parent topic:ZigBee Timer functions

ZTIMER_eInit

ZTIMER_teStatus ZTIMER_eInit(ZTIMER_tsTimer *psTimers,
                            uint8 u8NumTimers);

Description

This function initializes a set of software timers for use by the application. A list of timers is provided in an array, in which each array element is a structure containing information on one timer (see Section 10.2.2.1). The index of an array element is used as a reference for the corresponding timer.

In order to use one of the initialized timers, it must first be opened using ZTIMER_eOpen().

Parent topic:ZTIMER_eInit

Parameters

psTimers: Pointer to an array of structures, where each array element contains information for one timer (see Section 10.2.2.1)
u8NumTimers: Number of timers in the above array

Parent topic:ZTIMER_eInit

Returns

E_ZTIMER_OK (timers successfully initialized)
E_ZTIMER_FAIL (timers not initialized)

Parent topic:ZTIMER_eInit

Parent topic:ZigBee Timer functions

ZTIMER_eOpen

ZTIMER_teStatus ZTIMER_eOpen(
                    uint8 *pu8TimerIndex,
                    ZTIMER_tpfCallback pfCallback,
                    void *pvParams,
                    uint8 u8Flags);

Description

This function is used to open the specified software timer. A list of parameter values for the timer must be provided as well as a user-defined callback function that will be used to perform any operations required on expiration of the timer.

The callback function has the following prototype:

typedef void (*ZTIMER_tpfCallback)(void * pvParam );

where pvParam is a pointer to the timer parameters.

The function also includes a parameter u8Flags, which specifies whether the timer should allow or prevent sleep. When activity checks are made to decide whether the device can enter sleep mode, the value of this flag determines if the (running) timer will stop the device from going to sleep.

Before a timer is opened, it must have been initialized in a call to ZTIMER_eInit().

Parent topic:ZTIMER_eOpen

Parameters

pu8TimerIndex Pointer to location containing the index number of the timer in the list of timers initialized using ZTIMER_eInit()
pfCallback Pointer to the user-defined callback function for the timer
pvParams Pointer to a list of parameter values for the timer u8Flags Flag indicating whether the timer should allow or prevent sleep, one of:
- ZTIMER_FLAG_ALLOW_SLEEP
- ZTIMER_FLAG_PREVENT_SLEEP

Parent topic:ZTIMER_eOpen

Returns

E_ZTIMER_OK (timer successfully opened)
E_ZTIMER_FAIL (timer not opened)

Parent topic:ZTIMER_eOpen

Parent topic:ZigBee Timer functions

ZTIMER_eClose

ZTIMER_teStatus ZTIMER_eClose(uint8 u8TimerIndex);

Description

This function is used to close the specified software timer when it is no longer needed. The timer must have been previously opened using ZTIMER_eOpen().

Parent topic:ZTIMER_eClose

Parameters

u8TimerIndex: Index number of the timer in the list of timers initialized using ZTIMER_eInit().

Parent topic:ZTIMER_eClose

Returns

E_ZTIMER_OK (timer successfully closed)
E_ZTIMER_FAIL (timer not closed - may be running or already closed)

Parent topic:ZTIMER_eClose

Parent topic:ZigBee Timer functions

ZTIMER_eStart

ZTIMER_teStatus ZTIMER_eStart(uint8 u8TimerIndex,
                              uint32 u32Time);

Description

This function is used to start the specified software timer. The length of time for which the timer will run must be specified in milliseconds.

Before a timer is started, it must have been opened using ZTIMER_eOpen(). Once started, the timer can be stopped (before it expires) using ZTIMER_eStop().

Parent topic:ZTIMER_eStart

Parameters

pu8TimerIndex: Index number of the timer in the list of timers initialized using ZTIMER_eInit().
u32Time: The time, in milliseconds, for which the timer should run.

Parent topic:ZTIMER_eStart

Returns

E_ZTIMER_OK (timer successfully started)
E_ZTIMER_FAIL (timer not started)

Parent topic:ZTIMER_eStart

Parent topic:ZigBee Timer functions

ZTIMER_eStop

ZTIMER_teStatus ZTIMER_eStop(uint8 u8TimerIndex);

Description

This function is used to stop the specified software timer (before it expires). The timer must have been previously started using ZTIMER_eStart().

Parent topic:ZTIMER_eStop

Parameters

pu8TimerIndex: Index number of the timer in the list of timers initialized using ZTIMER_eInit().

Parent topic:ZTIMER_eStop

Returns

E_ZTIMER_OK (timer successfully stopped)
E_ZTIMER_FAIL (timer not stopped - may be already stopped or expired)

Parent topic:ZTIMER_eStop

Parent topic:ZigBee Timer functions

ZTIMER_eGetState

ZTIMER_teStatus ZTIMER_eGetState(uint8 u8TimerIndex);

Description

This function is used to obtain the current state of the specified software timer. The possible reported states are:

Running
Stopped
Expired
Closed

Parent topic:ZTIMER_eGetState

Parameters

pu8TimerIndex Index number of the timer in the list of timers initialized using ZTIMER_eInit().

Parent topic:ZTIMER_eGetState

Parent topic:ZigBee Timer functions

Parent topic:ZigBee Timer resources

ZigBee timer structures

ZTIMER_tsTimer

The ZigBee timer structure is shown below. It is used to represent a single software timer that may be used by the application.

typedef struct
{
     ZTIMER_teState      eState;
     uint32             u32Time;
     void               *pvParameters;
     ZTIMER_tpfCallback pfCallback;
} ZTIMER_tsTimer;

where:

eStaterepresents the current state of the timer, as one of:
- E_ZTIMER_STATE_CLOSED
- E_ZTIMER_STATE_STOPPED
- E_ZTIMER_STATE_RUNNING
- E_ZTIMER_STATE_EXPIRED
u32Timeis the remaining time, in milliseconds, that the timer still has to run
pvParametersis a pointer to a set of parameters used by the timer
pfCallbackis a pointer to the user-defined callback function that will be called when the timer expires - this function has the prototype:
```
typedef void \(\*ZTIMER\_tpfCallback\)\(void \pvParam*\);
```
where pvParam is a pointer to the timer parameters.

Parent topic:ZigBee timer structures

Parent topic:ZigBee Timer resources

Parent topic:General ZPS Resources

Critical Section and Mutex Resources

The Critical Section and Mutex functions are concerned with protecting sections of application code from preemption and re-entrancy. These resources are provided in the header file portmacro.h.

The Critical Section and Mutex functions are described in Section 10.3.1.
The Critical Section and Mutex structures are described in Section 10.3.2.

Critical Section and Mutex functions

The functions are listed below.

Function page

Parent topic:Critical Section and Mutex functions

ZPS_eEnterCriticalSection

uint8 ZPS_eEnterCriticalSection(
                    void *hMutex,
                    uint32* psIntStore);

Description

This function can be used to mark the end of a critical section of application code. The function ZPS_eEnterCriticalSection() must have been called at the start of the critical section.

This function can be used to mark the start of a critical section of application code - this is a code section that cannot be preempted by an interrupt with priority level less than 12. The function ZPS_eExitCriticalSection() must be called at the end of the critical section.

A pointer to a ‘priority level’ value must be provided, which contains the current priority level of the main application thread (when critical sections are not being executed). When a critical section is entered, the priority level of the main thread is increased such that interrupts with a priority of 11 or less cannot preempt the main thread. At the end of the critical section, the priority level of the main thread is returned to its value from before the critical section was entered.

Optionally, a mutex can also be applied during the critical section to protect the section from re-entrancy. If a mutex is required, a pointer must be provided to a user- defined mutex function with the following prototype:

((bool_t*) (*) (void))

This function must define and maintain a Boolean flag that indicates whether the corresponding mutex is active (TRUE) or inactive (FALSE). This flag is used by ZPS_eEnterCriticalSection() to determine whether the mutex is available.

If this flag reads as FALSE, the mutex is applied and the above mutex function must set the flag to TRUE.
If the flag is already TRUE, then the mutex cannot be applied - in this case, ZPS_eEnterCriticalSection() returns a failure.

Critical sections and mutexes are further described in Section 6.9.3.

Parent topic:ZPS_eEnterCriticalSection

Parameters

hMutex Pointer to user-defined mutex function (see above) - set to NULL if no mutex is required
psIntStore Pointer to structure containing ‘priority level’ value (see Section 10.3.2.1)

Parent topic:ZPS_eEnterCriticalSection

Returns

0x00 for success, 0x01 for failure (all other values are reserved)

Parent topic:ZPS_eEnterCriticalSection

Parent topic:Critical Section and Mutex functions

ZPS_eExitCriticalSection

uint8 ZPS_eExitCriticalSection(
                    void *hMutex,
                    uint32* psIntStore);

Description

This function can be used to mark the end of a critical section of application code. The function ZPS_eEnterCriticalSection() should be called at the start of the critical section.

A pointer to the ‘priority level’ value must be provided. If a mutex was used in the critical section, a pointer to the relevant mutex function must be provided in order to release the mutex.

Critical sections and mutexes are further described in Section 6.9.3.

Parent topic:ZPS_eExitCriticalSection

Parameters

hMutex Pointer to user-defined mutex function (see above) - set toNULL if no mutex was used.
psIntStore Pointer to structure containing ‘priority level’ value (see Section 10.3.2.1).

Parent topic:ZPS_eExitCriticalSection

Returns

0x00 for success, 0x01 for failure (all other values are reserved)

Parent topic:ZPS_eExitCriticalSection

Parent topic:Critical Section and Mutex functions

ZPS_u8GrabMutexLock

uint8 ZPS_u8GrabMutexLock(
                    void *hMutex,
                    uint32* psIntStore);

Description

This function can be used to apply a mutex at the start of a section of application code that is to be protected from re-entrancy. The function **ZPS_u8ReleaseMutexLock()**must be called at the end of the mutex-protected section to release the mutex.

A pointer must be provided to a user-defined mutex function with the following prototype:

((bool_t*) (*) (void))

This function must define and maintain a Boolean flag which indicates whether the corresponding mutex is active (TRUE) or inactive (FALSE). This flag is used by ZPS_u8GrabMutexLock() to determine whether the mutex is available. If this flag reads as FALSE, the mutex is applied and the above mutex function must set the flag to TRUE, but if the flag is already TRUE then the mutex cannot be applied - in the latter case, ZPS_u8GrabMutexLock() returns a failure.

A pointer to a ‘priority level’ value must be provided, which contains the current priority level of the main application thread (when mutex protection is not being implemented). When a mutex is applied, the priority level of the main thread is increased such that interrupts with a priority of 11 or less cannot preempt the main thread. When the mutex is released, the priority level of the main thread will be returned to its value from before the mutex was applied.

Mutexes are further described in Section 6.9.3.

Parent topic:ZPS_u8GrabMutexLock

Parameters

hMutex Pointer to user-defined mutex function (see above)
psIntStore Pointer to structure containing ‘priority level’ value (see Section 10.3.2.1).

Parent topic:ZPS_u8GrabMutexLock

Returns

0x00 for success, 0x01 for failure (all other values are reserved).

Parent topic:ZPS_u8GrabMutexLock

Parent topic:Critical Section and Mutex functions

ZPS_u8ReleaseMutexLock

uint8 ZPS_u8ReleaseMutexLock(
                    void *hMutex,
                    uint32* psIntStore);

Description

This function can be used to release a mutex that has been applied to a section of application code. The function ZPS_u8GrabMutexLock() must have been called at the start of the mutex-protected section.

A pointer to the relevant mutex function must be provided in order to release the mutex. A pointer to the ‘priority level’ value must also be provided.

Mutexes are further described in Section 6.9.3.

Parent topic:ZPS_u8ReleaseMutexLock

Parameters

hMutex Pointer to user-defined mutex function (see above).
psIntStore Pointer to structure containing ‘priority level’ value (see Section 10.3.2.1).

Parent topic:ZPS_u8ReleaseMutexLock

Returns

0x00 for success, 0x01 for failure (all other values are reserved)

Parent topic:ZPS_u8ReleaseMutexLock

Parent topic:Critical Section and Mutex functions

Parent topic:Critical Section and Mutex Resources

Critical Section and Mutex Structures

u32MicroIntStorage

u32MicroIntStorageis a 32-bit mask of the interrupts currently enabled. The u32MicroIntStoragestructure is used in critical sections and mutex-protected sections where u32MicroIntStoragetakes the interrupts that have been enabled.

Parent topic:Critical Section and Mutex Structures

Parent topic:Critical Section and Mutex Resources

Parent topic:General ZPS Resources