Contiki 2.6

Micro

Many of the supplied example applications use these microcontroller functions. More...

Defines

#define MICRO_DISABLE_WATCH_DOG_KEY   0xA5
 The value that must be passed as the single parameter to halInternalDisableWatchDog() in order to sucessfully disable the watchdog timer.
#define PORTA_PIN(y)   (PORTA|y)
 Some registers and variables require indentifying GPIO by a single number instead of the port and pin.
#define PORTB_PIN(y)   (PORTB|y)
 Some registers and variables require indentifying GPIO by a single number instead of the port and pin.
#define PORTC_PIN(y)   (PORTC|y)
 Some registers and variables require indentifying GPIO by a single number instead of the port and pin.
#define PORTx_PIN(x, y)   (x|y)
 Some registers and variables require indentifying GPIO by a single number instead of the port and pin.

Functions

void halInit (void)
 Initializes microcontroller-specific peripherals.
void halReboot (void)
 Restarts the microcontroller and therefore everything else.
void halPowerUp (void)
 Powers up microcontroller peripherals and board peripherals.
void halPowerDown (void)
 Powers down microcontroller peripherals and board peripherals.
void halInternalEnableWatchDog (void)
 Enables the watchdog timer.
void halInternalDisableWatchDog (int8u magicKey)
 Disables the watchdog timer.
boolean halInternalWatchDogEnabled (void)
 Determines whether the watchdog has been enabled or disabled.
void halCommonDelayMicroseconds (int16u us)
 Blocks the current thread of execution for the specified amount of time, in microseconds.
StStatus halBootloaderStart (int8u mode, int8u channel, int16u panId)
 Request the appplication to enter in bootloader mode.
void halInternalResetWatchDog (void)
 Resets the watchdog timer.
void halGpioConfig (int32u io, int32u config)
 Configure an IO pin's operating mode.
void halGpioSet (int32u io, boolean value)
 Set/Clear single GPIO bit.
void halInternalCalibrateSlowRc (void)
 Calibrates the internal SlowRC to generate a 1024 Hz (1kHz) clock.
void halInternalCalibrateFastRc (void)
 Calibrates the internal FastRC to generate a 12Mhz clock.
void halInternalSetRegTrim (boolean boostMode)
 Sets the trim values for the 1.8V and 1.2V regulators based upon manufacturing configuration.
int16u stMeasureVddSlow (void)
 Takes a slow ADC measurement of VDD_PADS in millivolts.
int16u stMeasureVddFast (void)
 Takes a fast ADC measurement of VDD_PADS in millivolts.
void halCommonCalibratePads (void)
 Calibrates the GPIO pads.
void halCommonCheckXtalBiasTrim (void)
 This function is intended to be called periodically, from the stack and application, to check the XTAL bias trim is within appropriate levels and adjust if not.
void halInternalSwitchToXtal (void)
 Switches to running off of the 24MHz crystal, including changing the CPU to be 24MHz (FCLK sourced from SYSCLK).
void halInternalSearchForBiasTrim (void)
 Search for optimal 24MHz crystal bias trim, assuming no valid prior value.
void halCommonDelayMilliseconds (int16u ms)
 Blocks the current thread of execution for the specified amount of time, in milliseconds.
void halSleepWithOptions (SleepModes sleepMode, int32u gpioWakeBitMask)
 Puts the microcontroller to sleep in a specified mode, allows the GPIO wake sources to be determined at runtime.
StStatus halSleepForQsWithOptions (int32u *duration, int32u gpioWakeBitMask)
 Uses the system timer to enter ::SLEEPMODE_WAKETIMER for approximately the specified amount of time (provided in quarter seconds), the GPIO wake sources can be provided at runtime.
void halInternalIdleSleep (void)
 Provides access to assembly code which triggers idle sleep.
void halInternalSleep (SleepModes sleepMode)
 Puts the microcontroller to sleep in a specified mode.
int32u halGetWakeInfo (void)
 Obtains the events that caused the last wake from sleep.
void halCommonSeedRandom (int32u seed)
 Seeds the halCommonGetRandom() pseudorandom number generator.
int16u halCommonGetRandom (void)
 Runs a standard LFSR to generate pseudorandom numbers.

Detailed Description

Many of the supplied example applications use these microcontroller functions.

See also hal/micro/cortexm3/micro.h for source code.

See hal/micro/micro-common.h for source code.


Define Documentation

#define PORTA_PIN (   y)    (PORTA|y)

Some registers and variables require indentifying GPIO by a single number instead of the port and pin.

This macro converts Port A pins into a single number.

Definition at line 36 of file micro-common.h.

Referenced by halBoardPowerUp().

#define PORTB_PIN (   y)    (PORTB|y)

Some registers and variables require indentifying GPIO by a single number instead of the port and pin.

This macro converts Port B pins into a single number.

Definition at line 42 of file micro-common.h.

Referenced by halBoardPowerDown(), halBoardPowerUp(), halInternalSleep(), and uartInit().

#define PORTC_PIN (   y)    (PORTC|y)

Some registers and variables require indentifying GPIO by a single number instead of the port and pin.

This macro converts Port C pins into a single number.

Definition at line 48 of file micro-common.h.

Referenced by halBoardPowerUp().

#define PORTx_PIN (   x,
 
)    (x|y)

Some registers and variables require indentifying GPIO by a single number instead of the port and pin.

This macro converts Port C pins into a single number.

Definition at line 55 of file micro-common.h.

Referenced by halBoardPowerDown(), halBoardPowerUp(), halInitButton(), and leds_arch_init().


Function Documentation

StStatus halBootloaderStart ( int8u  mode,
int8u  channel,
int16u  panId 
)

Request the appplication to enter in bootloader mode.

This function will check whwther the user flash contains the bootloader and if yes it will jump into it according to the user parameters.

Parameters:
modeThe bootloader mode, 0 UART mode, 1 RF mode. All other values are reserved
channelThe channel where the booloader will operate. 0 means default channel (only vaild for RF mode).
panIDThe panID where the booloader will operate. 0xFFFF means default panID (only vaild for RF mode).
Returns:
An error code or it will never return.

Definition at line 130 of file micro.c.

References halReboot(), IAP_BOOTLOADER_APP_SWITCH_SIGNATURE, IAP_BOOTLOADER_DEFAULT_CHANNEL, IAP_BOOTLOADER_MODE_OTA, and IAP_BOOTLOADER_MODE_UART.

void halCommonCalibratePads ( void  )

Calibrates the GPIO pads.

This function is called from within the stack and HAL at appropriate times.

Definition at line 192 of file micro-common-internal.c.

References stMeasureVddFast().

Referenced by halPowerUp().

void halCommonCheckXtalBiasTrim ( void  )

This function is intended to be called periodically, from the stack and application, to check the XTAL bias trim is within appropriate levels and adjust if not.

This function is *not* designed to be used before halInternalSwitchToXtal() has been called.

Definition at line 305 of file clocks.c.

void halCommonDelayMicroseconds ( int16u  us)

Blocks the current thread of execution for the specified amount of time, in microseconds.

The function is implemented with cycle-counted busy loops and is intended to create the short delays required when interfacing with hardware peripherals.

The accuracy of the timing provided by this function is not specified, but a general rule is that when running off of a crystal oscillator it will be within 10us. If the micro is running off of another type of oscillator (e.g. RC) the timing accuracy will potentially be much worse.

Parameters:
usThe specified time, in microseconds. Values should be between 1 and 65535 microseconds.

Definition at line 250 of file micro-common-internal.c.

Referenced by halCommonDelayMilliseconds(), halInternalCalibrateFastRc(), and halInternalCalibrateSlowRc().

void halCommonDelayMilliseconds ( int16u  ms)

Blocks the current thread of execution for the specified amount of time, in milliseconds.

The function is implemented with cycle-counted busy loops and is intended to create the short delays required when interfacing with hardware peripherals. This function works by simply adding another layer on top of halCommonDelayMicroseconds().

Parameters:
msThe specified time, in milliseconds.

Definition at line 284 of file micro-common-internal.c.

References halCommonDelayMicroseconds().

int16u halCommonGetRandom ( void  )

Runs a standard LFSR to generate pseudorandom numbers.

Called by the MAC in the stack to choose random backoff slots.

Complicated implementations may improve the MAC's ability to avoid collisions in large networks, but it is critical to implement this function to return quickly.

Definition at line 96 of file micro.c.

void halCommonSeedRandom ( int32u  seed)

Seeds the halCommonGetRandom() pseudorandom number generator.

It should be called by the application during initialization with a seed from the radio randon number generator.

Parameters:
seedA seed for the pseudorandom number generator.

Definition at line 76 of file micro.c.

int32u halGetWakeInfo ( void  )

Obtains the events that caused the last wake from sleep.

The meaning of each bit is as follows:

  • [31] = WakeInfoValid
  • [30] = SleepSkipped
  • [29] = CSYSPWRUPREQ
  • [28] = CDBGPWRUPREQ
  • [27] = PWRUP_WAKECORE
  • [26] = PWRUP_SLEEPTMRWRAP
  • [25] = PWRUP_SLEEPTMRCOMPB
  • [24] = PWRUP_SLEEPTMRCOMPA
  • [23:0] = corresponding GPIO activity

WakeInfoValid means that halSleepWithOptions (halInternalSleep) has been called at least once. Since the power on state clears the wake event info, this bit says the sleep code has been called since power on.

SleepSkipped means that the chip never left the running state. Sleep can be skipped if any wake event occurs between going ATOMIC and transferring control from the CPU to the power management state machine. Sleep can also be skipped if the debugger is connected (JTAG/SerialWire CSYSPWRUPREQ signal is set). The net affect of skipping sleep is the Low Voltage domain never goes through a power/reset cycle.

Returns:
The events that caused the last wake from sleep.

Definition at line 122 of file sleep.c.

void halGpioConfig ( int32u  io,
int32u  config 
)

Configure an IO pin's operating mode.

Parameters:
ioThe io pin to use, can be specified with the convenience macros PORTA_PIN(), PORTB_PIN(), PORTC_PIN()
configThe configuration mode to use.

Definition at line 48 of file micro-common.c.

Referenced by halBoardPowerDown(), halBoardPowerUp(), halInitButton(), halInitLed(), leds_arch_init(), temperatureSensor_Init(), and uartInit().

void halGpioSet ( int32u  io,
boolean  value 
)

Set/Clear single GPIO bit.

Parameters:
ioThe io pin to use, can be specified with the convenience macros PORTA_PIN(), PORTB_PIN(), PORTC_PIN()
valueA flag indicating whether to set or clear the io.

Definition at line 63 of file micro-common.c.

References BIT.

Referenced by halBoardPowerDown(), halBoardPowerUp(), halClearLed(), halInitButton(), and halSetLed().

void halInternalDisableWatchDog ( int8u  magicKey)

Disables the watchdog timer.

Note:
To prevent the watchdog from being disabled accidentally, a magic key must be provided.
Parameters:
magicKeyA value (MICRO_DISABLE_WATCH_DOG_KEY) that enables the function.

Definition at line 31 of file micro-common.c.

References MICRO_DISABLE_WATCH_DOG_KEY.

Referenced by halInternalSleep().

void halInternalResetWatchDog ( void  )

Resets the watchdog timer.

This function is pointed to by the macro halResetWatchdog().

Warning:
Be very careful when using this as you can easily get into an infinite loop.

Definition at line 25 of file micro-common.c.

void halInternalSearchForBiasTrim ( void  )

Search for optimal 24MHz crystal bias trim, assuming no valid prior value.

This function is typically called during initialization of the microcontroller.

Definition at line 338 of file clocks.c.

Referenced by halInternalSwitchToXtal().

void halInternalSetRegTrim ( boolean  boostMode)

Sets the trim values for the 1.8V and 1.2V regulators based upon manufacturing configuration.

Parameters:
boostModeAlter the regulator trim based upon the state of boost mode. TRUE if boost mode is active, FALSE otherwise.

Definition at line 202 of file micro-common-internal.c.

Referenced by halInit().

void halInternalSleep ( SleepModes  sleepMode)

Puts the microcontroller to sleep in a specified mode.

This internal function performs the actual sleep operation. This function assumes all of the wake source registers are configured properly.

Note:
This routine always enables interrupts.
Parameters:
sleepModeA microcontroller sleep mode

Definition at line 127 of file sleep.c.

References BIT, BIT32, FALSE, halInternalDisableWatchDog(), halInternalEnableWatchDog(), halInternalIdleSleep(), halInternalWatchDogEnabled(), INTERRUPTS_OFF, INTERRUPTS_ON, MICRO_DISABLE_WATCH_DOG_KEY, PORTB_PIN, and TRUE.

Referenced by halSleepWithOptions().

void halInternalSwitchToXtal ( void  )

Switches to running off of the 24MHz crystal, including changing the CPU to be 24MHz (FCLK sourced from SYSCLK).

The switch function will respect the BIASTRIM HI and LO flags and adjust bias trim until appropriate crystal biasing is used. This function is called from within the stack and HAL at appropriate times.

Definition at line 397 of file clocks.c.

boolean halInternalWatchDogEnabled ( void  )

Determines whether the watchdog has been enabled or disabled.

Returns:
A boolean value indicating if the watchdog is current enabled.

Definition at line 39 of file micro-common.c.

References FALSE, and TRUE.

Referenced by halInternalSleep().

StStatus halSleepForQsWithOptions ( int32u *  duration,
int32u  gpioWakeBitMask 
)

Uses the system timer to enter ::SLEEPMODE_WAKETIMER for approximately the specified amount of time (provided in quarter seconds), the GPIO wake sources can be provided at runtime.

This function returns ::ST_SUCCESS and the duration parameter is decremented to 0 after sleeping for the specified amount of time. If an interrupt occurs that brings the chip out of sleep, the function returns ::ST_SLEEP_INTERRUPTED and the duration parameter reports the amount of time remaining out of the original request.

Note:
This routine always enables interrupts.
The maximum sleep time of the hardware is limited on STM32W108 platforms to 48.5 days. Any sleep duration greater than this limit will wake up briefly (e.g. 16 microseconds) to reenable another sleep cycle.
Parameters:
durationThe amount of time, expressed in quarter seconds, that the micro should be placed into ::SLEEPMODE_WAKETIMER. When the function returns, this parameter provides the amount of time remaining out of the original sleep time request (normally the return value will be 0).
gpioWakeBitMaskA bit mask of the GPIO that are allowed to wake the chip from deep sleep. A high bit in the mask will enable waking the chip if the corresponding GPIO changes state. bit0 is PA0, bit1 is PA1, bit8 is PB0, bit16 is PCO, bit23 is PC7, bits[31:24] are ignored.
Returns:
An StStatus value indicating the success or failure of the command.

Definition at line 168 of file system-timer.c.

References TRUE.

void halSleepWithOptions ( SleepModes  sleepMode,
int32u  gpioWakeBitMask 
)

Puts the microcontroller to sleep in a specified mode, allows the GPIO wake sources to be determined at runtime.

This function requires the GPIO wake sources to be defined at compile time in the board file.

Note:
This routine always enables interrupts.
Parameters:
sleepModeA microcontroller sleep mode.
gpioWakeBitMaskA bit mask of the GPIO that are allowed to wake the chip from deep sleep. A high bit in the mask will enable waking the chip if the corresponding GPIO changes state. bit0 is PA0, bit1 is PA1, bit8 is PB0, bit16 is PCO, bit23 is PC7, bits[31:24] are ignored.
See also:
::SleepModes

Definition at line 848 of file sleep.c.

References halInternalSleep().

Referenced by main().

int16u stMeasureVddFast ( void  )

Takes a fast ADC measurement of VDD_PADS in millivolts.

Due to the conversions performed, this function takes slightly under 150us with a variation across successive conversions approximately +/-20mv of the average conversion.

Returns:
A fast measurement of VDD_PADS in millivolts.

Definition at line 140 of file micro-common-internal.c.

Referenced by halCommonCalibratePads().

int16u stMeasureVddSlow ( void  )

Takes a slow ADC measurement of VDD_PADS in millivolts.

Due to the conversions performed, this function takes slightly under 3.2ms with a variation across successive conversions approximately +/-2mv of the average conversion.

Returns:
A slow measurement of VDD_PADS in millivolts.