Detailed Description

This provides an abstraction layer for general functionality used by the MM-IoT-SDK examples.

Note: This API is not used by morselib.

Macros
#define	LED_OFF 0
	A value of 0 turns OFF an LED. More...

#define	LED_ON 255
	A value of 255 turns an LED ON fully. More...

#define	MMHAL_DEBUG_PIN(_pin_num) (1ul << (_pin_num))
	Macro to simplify debug pin mask/value definition. More...

#define	MMHAL_ALL_DEBUG_PINS (UINT32_MAX)
	Bit mask with all debug pins selected. More...

Typedefs
typedef void(*	mmhal_button_state_cb_t) (enum mmhal_button_id button_id, enum mmhal_button_state button_state)
	Button state callback function prototype. More...

Enumerations
enum	mmhal_led_id { LED_RED , LED_GREEN , LED_BLUE , LED_WHITE }
	Enumeration for different LEDs on the board. More...

enum	mmhal_button_id { BUTTON_ID_USER0 }
	Enumeration for buttons on the board. More...

enum	mmhal_button_state { BUTTON_RELEASED , BUTTON_PRESSED }
	Enumeration for button states. More...

Functions
void	mmhal_set_led (uint8_t led, uint8_t level)
	Set the specified LED to the requested level. More...

void	mmhal_set_error_led (bool state)
	Set the error LED to the requested state. More...

bool	mmhal_set_button_callback (enum mmhal_button_id button_id, mmhal_button_state_cb_t button_state_cb)
	Registers a callback handler for button state changes. More...

mmhal_button_state_cb_t	mmhal_get_button_callback (enum mmhal_button_id button_id)
	Returns the registered callback handler for button state changes. More...

enum mmhal_button_state	mmhal_get_button (enum mmhal_button_id button_id)
	Reads the state of the specified button. More...

bool	mmhal_get_hardware_version (char *version_buffer, size_t version_buffer_length)
	Reads information that can be used to identify the hardware platform, such as hardware ID and version number, in the form of a user readable string. More...

void	mmhal_set_debug_pins (uint32_t mask, uint32_t values)
	Set the value one or more debug pins. More...

time_t	mmhal_get_time (void)
	Returns the time of day as set in the RTC. More...

void	mmhal_set_time (time_t epoch)
	Sets the RTC to the specified time in UTC. More...

Macro Definition Documentation

◆ LED_OFF

#define LED_OFF 0

A value of 0 turns OFF an LED.

Definition at line 44 of file mmhal_app.h.

◆ LED_ON

#define LED_ON 255

A value of 255 turns an LED ON fully.

Some boards support varying an LED's brightness. For these boards a value between 1 and 255 will result in proportionately varying levels of brightness. LED's that do not have a brightness control feature will just turn ON fully for any non zero value.

Definition at line 53 of file mmhal_app.h.

◆ MMHAL_ALL_DEBUG_PINS

#define MMHAL_ALL_DEBUG_PINS (UINT32_MAX)

Bit mask with all debug pins selected.

Definition at line 156 of file mmhal_app.h.

◆ MMHAL_DEBUG_PIN

#define MMHAL_DEBUG_PIN ( _pin_num ) (1ul << (_pin_num))

Macro to simplify debug pin mask/value definition.

Parameters

_pin_num The pin number to set in the mask. Must be 0-31 (inclusive).

Example:

mmhal_set_debug_pins(MMHAL_DEBUG_PIN(0), MMHAL_DEBUG_PIN(0));

Definition at line 153 of file mmhal_app.h.

Typedef Documentation

◆ mmhal_button_state_cb_t

typedef void(* mmhal_button_state_cb_t) (enum mmhal_button_id button_id, enum mmhal_button_state button_state)

Button state callback function prototype.

Definition at line 97 of file mmhal_app.h.

Enumeration Type Documentation

◆ mmhal_button_id

enum mmhal_button_id

Enumeration for buttons on the board.

Note: The support for each button is platform dependent.

Definition at line 82 of file mmhal_app.h.

◆ mmhal_button_state

enum mmhal_button_state

Enumeration for button states.

Definition at line 90 of file mmhal_app.h.

◆ mmhal_led_id

enum mmhal_led_id

Enumeration for different LEDs on the board.

Note: Some of these LEDs may not be available on all boards and some of these values may refer to the same LED.

Definition at line 35 of file mmhal_app.h.

Function Documentation

◆ mmhal_get_button()

enum mmhal_button_state mmhal_get_button ( enum mmhal_button_id button_id )

Reads the state of the specified button.

Parameters

button_id The button state to read

Returns: The current button state, or BUTTON_RELEASED if not supported

◆ mmhal_get_button_callback()

mmhal_button_state_cb_t mmhal_get_button_callback ( enum mmhal_button_id button_id )

Returns the registered callback handler for button state changes.

Parameters

button_id The button whose callback should be returned

Returns: The registered callback or NULL if no callback registered

◆ mmhal_get_hardware_version()

bool mmhal_get_hardware_version	(	char *	version_buffer,
		size_t	version_buffer_length
	)

Reads information that can be used to identify the hardware platform, such as hardware ID and version number, in the form of a user readable string.

This function attempts to detect the correct hardware and version. The actual means of detecting the correct hardware and version will vary from implementation to implementation and may use means such as identification information stored in EEPROM or devices detected on GPIO, SPI or I2C interfaces. Returns false if the hardware could not be identified correctly.

Parameters

version_buffer	The pre-allocated buffer to return the hardware ID and version in.
version_buffer_length	The length of the pre-allocated buffer.

Returns: True if the hardware was correctly identified and returned.

◆ mmhal_get_time()

time_t mmhal_get_time ( void )

Returns the time of day as set in the RTC.

Time is in UTC.

Returns: Epoch time (seconds since 1 Jan 1970) or 0 on failure.

◆ mmhal_set_button_callback()

bool mmhal_set_button_callback	(	enum mmhal_button_id	button_id,
		mmhal_button_state_cb_t	button_state_cb
	)

Registers a callback handler for button state changes.

Note: The callback will be executed in an Interrupt Service Routine context

Parameters

button_id	The button whose state should be reported to the callback
button_state_cb	The function to call on button state change, or NULL to disable.

Returns: True if the callback is registered successfully, False if not supported

◆ mmhal_set_debug_pins()

void mmhal_set_debug_pins	(	uint32_t	mask,
		uint32_t	values
	)

Set the value one or more debug pins.

Each platform can define up to 32 GPIOs for application use. If a GPIO is not supported by a platform then attempts to set it will be silently ignored. These GPIOs are intended for debug/test purposes.

Parameters

mask	Mask of GPIOs to modify. Each bit in this mask that is set will result in the corresponding GPIO being being set to the corresponding value given in `values`.
values	Bit field, where each bit corresponds to a GPIO, specifying the direction to drive each GPIO with 1 meaning drive high and 0 meaning drive low. Only GPIOs with the corresponding bit set in `mask` will be modified.

See also: MM_DEBUG_PIN_MASK

◆ mmhal_set_error_led()

void mmhal_set_error_led ( bool state )

Set the error LED to the requested state.

Note: This function is called by the bootloader and so needs to do all the initialization required to set the LED's as the bootloader does not use the regular BSP initialization located in main.c for configuring GPIO's and setting clock gates as required.

Parameters

state Set to true if the LED needs to be turned on, or false if the led needs to be turned off.

◆ mmhal_set_led()

void mmhal_set_led	(	uint8_t	led,
		uint8_t	level
	)

Set the specified LED to the requested level.

Do nothing if the requested LED does not exist.

Parameters

led	The LED to set, if the platform supports it. See mmhal_led_id
level	The level to set it to. 0 means OFF and non-zero means ON. If the platform supports brightness levels then 255 is full. Defines LED_ON and LED_OFF are provided for ease of use.

◆ mmhal_set_time()

void mmhal_set_time ( time_t epoch )

Sets the RTC to the specified time in UTC.

Note: While Unix epoch time supports years from 1970, most Real Time Clock chips support years from 2000 only as they store the year as years from 2000. So do not attempt to set any years below 2000 as this could cause the year to wrap around to an unreasonably high value. Definitely do not do:
mmhal_set_time(0);

mmhal_set_time
void mmhal_set_time(time_t epoch)
Sets the RTC to the specified time in UTC.

Parameters

epoch Time in Unix epoch time (seconds since 1 Jan 1970).

Detailed Description

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ LED_OFF

◆ LED_ON

◆ MMHAL_ALL_DEBUG_PINS

◆ MMHAL_DEBUG_PIN

Typedef Documentation

◆ mmhal_button_state_cb_t

Enumeration Type Documentation

◆ mmhal_button_id

◆ mmhal_button_state

◆ mmhal_led_id

Function Documentation

◆ mmhal_get_button()

◆ mmhal_get_button_callback()

◆ mmhal_get_hardware_version()

◆ mmhal_get_time()

◆ mmhal_set_button_callback()

◆ mmhal_set_debug_pins()

◆ mmhal_set_error_led()

◆ mmhal_set_led()

◆ mmhal_set_time()