Developing with ZBOSS for Zigbee

Macros

#define ZB_MAX_TIME_VAL   ZB_UINT32_MAX
 
#define ZB_MIN_TIME_VAL   ZB_UINT32_MIN
 
#define ZB_HALF_MAX_TIME_VAL   (ZB_MAX_TIME_VAL / 2U)
 
#define ZB_TIMER_GET()   (zb_timer_get())
 
#define ZB_TIME_SUBTRACT(a, b)   ((zb_time_t)((a) - (b)) < ZB_HALF_MAX_TIME_VAL ? (zb_time_t)((a) - (b)) : (zb_time_t)((b) - (a)))
 
#define ZB_TIME_ADD(a, b)   (zb_time_t)((a) + (b))
 
#define ZB_TIME_GE(a, b)   ((zb_time_t)((a) - (b)) < ZB_HALF_MAX_TIME_VAL)
 
#define ZB_TIME_ONE_SECOND   ZB_MILLISECONDS_TO_BEACON_INTERVAL(1000U)
 
#define ZB_MILLISECONDS_TO_BEACON_INTERVAL_CEIL(ms)   (((zb_time_t)(ms) * 1000U + (ZB_BEACON_INTERVAL_USEC - 1U)) / ZB_BEACON_INTERVAL_USEC)
 
#define ZB_MILLISECONDS_TO_BEACON_INTERVAL_FLOOR(ms)   ((zb_time_t)(ms) * 1000U / ZB_BEACON_INTERVAL_USEC)
 
#define ZB_MILLISECONDS_TO_BEACON_INTERVAL(ms)   ZB_MILLISECONDS_TO_BEACON_INTERVAL_CEIL(ms)
 
#define ZB_BEACON_INTERVAL_USEC   (ZB_SYMBOL_DURATION_USEC * ZB_ABASE_SUPERFRAME_DURATION)
 
#define ZB_TIME_BEACON_INTERVAL_TO_MSEC(t)   ((ZB_BEACON_INTERVAL_USEC * (zb_time_t)(t)) / 1000U)
 
#define ZB_TIME_BEACON_INTERVAL_TO_USEC(t)   ((zb_uint64_t)ZB_BEACON_INTERVAL_USEC * (t))
 
#define ZB_TIME_QUARTERECONDS(n)   (ZB_TIME_BEACON_INTERVAL_TO_MSEC((n)) / 250U)
 
#define ZB_MSEC_TO_QUARTERECONDS(n)   ((n) / 250U)
 
#define ZB_QUARTERECONDS_TO_MSEC(n)   250UL*(n)
 
#define ZB_QUARTERECONDS_TO_BEACON_INTERVAL(qsec)   ZB_MILLISECONDS_TO_BEACON_INTERVAL(250U * (qsec))
 
#define ZB_SECONDS_TO_MILLISECONDS(_s)   (1000ul*(_s))
 
#define ZB_SECONDS_TO_BEACON_INTERVAL(_s)   ZB_MILLISECONDS_TO_BEACON_INTERVAL(1000UL * (_s))
 
#define ZB_MILLISECONDS_TO_USEC(ms)   ((ms) * (1000u))
 
#define ZB_USECS_TO_MILLISECONDS(usec)   ((usec) / (1000u))
 

Typedefs

typedef zb_uint32_t zb_time_t
 

Detailed Description

ZBOSS time subsystem is based on hardware timer. There is a special zb_time_t type defined in ZBOSS API for working with time variables in ZBOSS framework. The zb_time_t type size may be limited depending on a platform. ZBOSS handles the overflow.

The basic time measurement unit is "beacon interval" (tick) equal to 15.36 microseconds (see Zigbee specification revision 22 section 3.6.4.1 Scheduling Method).

Macro Definition Documentation

◆ ZB_BEACON_INTERVAL_USEC

#define ZB_BEACON_INTERVAL_USEC   (ZB_SYMBOL_DURATION_USEC * ZB_ABASE_SUPERFRAME_DURATION)

Beacon interval in microseconds

1 beacon interval = aBaseSuperframeDuration * symbol duration

1 symbol = 16e-6 sec (mac spec 6.5.3.2 Symbol rate) for 2.4GHz ZB. 1 beacon interval = 15.360 ms.

◆ ZB_HALF_MAX_TIME_VAL

#define ZB_HALF_MAX_TIME_VAL   (ZB_MAX_TIME_VAL / 2U)

A half of defined maximum timer value.

◆ ZB_MAX_TIME_VAL

#define ZB_MAX_TIME_VAL   ZB_UINT32_MAX

Maximum timer value, if 32-bit timer is used.

◆ ZB_MILLISECONDS_TO_BEACON_INTERVAL

#define ZB_MILLISECONDS_TO_BEACON_INTERVAL (   ms)    ZB_MILLISECONDS_TO_BEACON_INTERVAL_CEIL(ms)

Convert time from milliseconds to beacon intervals.

◆ ZB_MILLISECONDS_TO_BEACON_INTERVAL_CEIL

#define ZB_MILLISECONDS_TO_BEACON_INTERVAL_CEIL (   ms)    (((zb_time_t)(ms) * 1000U + (ZB_BEACON_INTERVAL_USEC - 1U)) / ZB_BEACON_INTERVAL_USEC)

Convert time from milliseconds to beacon intervals (32-bit platforms). Round the result up.

◆ ZB_MILLISECONDS_TO_BEACON_INTERVAL_FLOOR

#define ZB_MILLISECONDS_TO_BEACON_INTERVAL_FLOOR (   ms)    ((zb_time_t)(ms) * 1000U / ZB_BEACON_INTERVAL_USEC)

Convert time from milliseconds to beacon intervals (32-bit platforms). Round the result down.

◆ ZB_MILLISECONDS_TO_USEC

#define ZB_MILLISECONDS_TO_USEC (   ms)    ((ms) * (1000u))

Convert from milliseconds to microseconds

◆ ZB_MIN_TIME_VAL

#define ZB_MIN_TIME_VAL   ZB_UINT32_MIN

Minimum timer value, if 32-bit timer is used.

◆ ZB_MSEC_TO_QUARTERECONDS

#define ZB_MSEC_TO_QUARTERECONDS (   n)    ((n) / 250U)

Convert from msec to quarterseconds

◆ ZB_QUARTERECONDS_TO_BEACON_INTERVAL

#define ZB_QUARTERECONDS_TO_BEACON_INTERVAL (   qsec)    ZB_MILLISECONDS_TO_BEACON_INTERVAL(250U * (qsec))

Convert from quarterseconds to beacon

◆ ZB_QUARTERECONDS_TO_MSEC

#define ZB_QUARTERECONDS_TO_MSEC (   n)    250UL*(n)

Convert from quarterseconds to msec

◆ ZB_SECONDS_TO_BEACON_INTERVAL

#define ZB_SECONDS_TO_BEACON_INTERVAL (   _s)    ZB_MILLISECONDS_TO_BEACON_INTERVAL(1000UL * (_s))

Convert from seconds to beacon

This macro works correctly on 32-bit platforms for intervals smaller than 71 minutes. The calculation was not tested on 16-bit platforms.

◆ ZB_SECONDS_TO_MILLISECONDS

#define ZB_SECONDS_TO_MILLISECONDS (   _s)    (1000ul*(_s))

Convert from seconds to milliseconds

◆ ZB_TIME_ADD

#define ZB_TIME_ADD (   a,
 
)    (zb_time_t)((a) + (b))

Time add: add 'a' to 'b'

Overflow is possible, but this is ok - it handled by subtraction and compare macros.

Parameters
a- time to add to
b- value to add
Returns
addition result

◆ ZB_TIME_BEACON_INTERVAL_TO_MSEC

#define ZB_TIME_BEACON_INTERVAL_TO_MSEC (   t)    ((ZB_BEACON_INTERVAL_USEC * (zb_time_t)(t)) / 1000U)

Convert time from beacon intervals to milliseconds (32-bit platform).

◆ ZB_TIME_BEACON_INTERVAL_TO_USEC

#define ZB_TIME_BEACON_INTERVAL_TO_USEC (   t)    ((zb_uint64_t)ZB_BEACON_INTERVAL_USEC * (t))

Convert time from beacon intervals to microseconds

◆ ZB_TIME_GE

#define ZB_TIME_GE (   a,
 
)    ((zb_time_t)((a) - (b)) < ZB_HALF_MAX_TIME_VAL)

Compare times a and b - check that a >= b

Taking into account overflow and unsigned values arithmetic and supposing difference between a and b can't be > 1/2 of the overall time values diapason, a >= b only if a - b < values_diapason/2

Parameters
a- first time value to compare
b- second time value to compare
Returns
1 is a >= b, 0 otherwise

◆ ZB_TIME_ONE_SECOND

#define ZB_TIME_ONE_SECOND   ZB_MILLISECONDS_TO_BEACON_INTERVAL(1000U)

One second timeout

◆ ZB_TIME_QUARTERECONDS

#define ZB_TIME_QUARTERECONDS (   n)    (ZB_TIME_BEACON_INTERVAL_TO_MSEC((n)) / 250U)

Quarterseconds timeout

◆ ZB_TIME_SUBTRACT

#define ZB_TIME_SUBTRACT (   a,
 
)    ((zb_time_t)((a) - (b)) < ZB_HALF_MAX_TIME_VAL ? (zb_time_t)((a) - (b)) : (zb_time_t)((b) - (a)))

Time subtraction: subtract 'b' from 'a'

Take overflow into account: change sign (subtraction order) if result > values_diapason/2. Suppose a always >= b, so result is never negative. This macro will be used to calculate, for example, amount of time to sleep

  • it is positive by definition. Do not use it to compare time values! Use ZB_TIME_GE() instead.
    Note
    Both a and b is of type zb_time_t. Can't decrease time (subtract constant from it) using this macro.
    Parameters
    a- time to subtract from
    b- time to subtract
    Returns
    subtraction result

◆ ZB_TIMER_GET

#define ZB_TIMER_GET ( )    (zb_timer_get())
Returns
Get current timer value (beacon intervals)

◆ ZB_USECS_TO_MILLISECONDS

#define ZB_USECS_TO_MILLISECONDS (   usec)    ((usec) / (1000u))

Convert from microseconds to milliseconds

Typedef Documentation

◆ zb_time_t

Timer functionality.

The idea is: platform has some timer which can be stopped or run. When run, it increments (or decrements - depends on platform) some counter until counter overflow (underflow), then issues interrupt - wakeups main loop if it sleeping. Time stored in ticks; time resolution is platform dependent, its usual value is 15.36 usec - 1 beacon interval.

Note
Time type has limited capacity (usually 16 bits) and can overflow. Macros which works with time handles overflow. It is supposed that time values will not differ to more then 1/2 of the maximum time value.

All that timer macros will not be used directly by the application code - it is scheduler internals. The only API for timer is ZB_SCHEDULE_ALARM() call. Timer type.