ZMOD4510 Nitrogen Dioxide and Ozone Firmware Documentation |

Modules | Files | Functions | Data Structures | Typedefs | Enumerations
Hardware Abstraction Layer API

Hardware abstraction layer (HAL) API, used by Renesas Environmental Sensor APIs to physically access the sensor. More...

## Modules
| ComBoard HAL
| Renesas communication board HAL.
| Raspberry Pi HAL
| Renesas communication board HAL.
| Custom HAL Template
| Template file for customer specific HAL implementation.

## Files
file | zmod4xxx_hal.h
| ZMOD4xxx specific hardware abstraction layer definitions.
file | hal.h
| Renesas Environmental Sensor HAL definitions.

## Functions
int | zmod4xxx_init (zmod4xxx_dev_t *dev, Interface_t *hal)
int | HAL_Init (Interface_t *hal)
| Initialize hardware and populate Interface_t object. More...
int | HAL_Deinit (Interface_t *hal)
| Cleanup before program exit. More...
void | HAL_HandleError (int errorCode, void const *context)
| Error handling function. More...
int | HAL_SetError (int error, int scope, ErrorStringGenerator_t errStrFn)
| Function storing error information. More...
char const * | HAL_GetErrorInfo (int *error, int *scope, char *str, int bufSize)
| Get detailed information for last error. More...
char const * | HAL_GetErrorString (int error, int scope, char *str, int bufSize)
| Error string generator for HAL-scoped errors. More...

## Data Structures
struct | Interface_t
| A structure of pointers to hardware specific functions. More...

## Typedefs
typedef int(* | I2CImpl_t) (void *, uint8_t, uint8_t *, int, uint8_t *, int)
| Function pointer type defining signature of I2C functions. More...
typedef char const *(* | ErrorStringGenerator_t) (int, int, char *, int)
| Function type used for generation of error strings. More...

## Enumerations
enum | GenericError_t { ecSuccess = 0, ecHALError = 0x100 }
| Error code definitions. More...
enum | ErrorScope_t { esSensor = 0x0000, esAlgorithm = 0x1000, esInterface = 0x2000, esHAL = 0x3000 }
| Success status code and error scopes. More...
enum | HALError_t { heNoInterface = 1, heNotImplemented, heI2CReadMissing, heI2CWriteMissing, heSleepMissing, heResetMissing }
| HAL scope error definitions. More...

## Detailed Description

Hardware abstraction layer (HAL) API, used by Renesas Environmental Sensor APIs to physically access the sensor.

The HAL API is a generic API that is used by all Renesas types of Environmental Sensors. It defines the interface that the sensor API can use to access the sensor on an arbitrary hardware platform. Renesas provides HAL implementations for EVK boards, Raspberry PI and Arduino. In order to use a specific sensor API in the customer application, the customer must implement the HAL API for his hardware platform. For that purpose, the template file template.c is provided, which must be adapted to work on the customer hardware. Please refer to the comments in the template file and the documentation of the HAL API for details.

All HAL API related files are located in path src/hal and its subdirectories.

## Data Structure Documentation

## ◆ Interface_t

struct Interface_t

A structure of pointers to hardware specific functions.

### Data Fields
void * | handle
I2CImpl_t | i2cRead
I2CImpl_t | i2cWrite
void(* | msSleep )(uint32_t ms)
int(* | reset )(void *handle)

#### Field Documentation

## ◆ handle

void* handle

handle to physical interface

## ◆ i2cRead

I2CImpl_t i2cRead

Pointer to I2C read implementation

The read operation may be preceded by a write to the same slave address. The function accepts a pointer to the interface handle, the slave address of the device to communicate with and two pairs of buffer pointer and buffer length. The first pair of buffer pointer / buffer length defines the data to be written, the second pair provides the pointer to the buffer where received data is stored and how many bytes shall be read. If the length field of the first buffer is not zero, the implementation must send an I2C write condition on the bus, transfer the data and send a repeated start condition followed by the corresponding read condition on the bus. If the length parameter of the first buffer is zero, no write is generated and the read is started immediately. The transmission must be terminated with a stop condition on the bus.

## ◆ i2cWrite

I2CImpl_t i2cWrite

Pointer to I2C write implementation

For convenience, the write operation accepts two pairs of buffer pointer and buffer length. This allows to transfer addresses or commands prior to data without the need to manually concatenate transmit data in a buffer. The implementation of this function must generate a start condition followed by the I2C slave address of the target device, followed by all data from both buffers. At the end of the transmission a stop bit must be generated on the bus.

## ◆ msSleep

void( * msSleep) (uint32_t ms)

Pointer to delay function

An implementation must delay execution by the specified number of `ms`

## ◆ reset

int( * reset) (void *handle)

Pointer to reset function

Implementation must pulse the reset pin

## Typedef Documentation

## ◆ ErrorStringGenerator_t

typedef char const*( * ErrorStringGenerator_t) (int, int, char *, int)

Function type used for generation of error strings.

Functions of this type may be passed to HAL_SetError() to generate meaningful descriptions of error conditions.

## ◆ I2CImpl_t

typedef int( * I2CImpl_t) (void *, uint8_t, uint8_t *, int, uint8_t *, int)

Function pointer type defining signature of I2C functions.

This function pointer typedef is used in Interface_t objects to hold pointers to I2C implementations of read and write.

## Enumeration Type Documentation

## ◆ ErrorScope_t

enum ErrorScope_t

Success status code and error scopes.

Enumerator
esSensor | Sensor scope
esAlgorithm | Algorithm scope
esInterface | Interface scope
esHAL | HAL scope

## ◆ GenericError_t

enum GenericError_t

Error code definitions.

Enumerator
ecSuccess | Operation completed successfully
ecHALError | Returned by sensor API if a HAL function failed. Specific information about the error can be obtained using the function HAL_GetErrorInfo().

## ◆ HALError_t

enum HALError_t

HAL scope error definitions.

When sensors are initialized (e.g. init_hardware()), the hal objects is checked whether all HAL functions required by the sensor are provided. If a function is missing one of the errors from this enumeration is returned.

Enumerator
heNoInterface | There was no interface found
heNotImplemented | The requested function is not implemented
heI2CReadMissing | Interface_t::i2cRead not provided
heI2CWriteMissing | Interface_t::i2cWrite not provided
heSleepMissing | Interface_t::msSleep not provided
heResetMissing | Interface_t::reset not provided

## Function Documentation

## ◆ HAL_Deinit()

int HAL_Deinit | ( | Interface_t * | hal | ) |

Cleanup before program exit.

This function shall free up resources that have been allocated through HAL_Init().

Parameters

  hal | pointer to Interface_t object to be deinitialized

Returns
  error code

Return values

  0 | on success
  !=0 | in case of error

## ◆ HAL_GetErrorInfo()

char const* HAL_GetErrorInfo | ( | int * | error,
|  | int * | scope,
|  | char * | str,
|  | int | bufSize
| ) |  |

Get detailed information for last error.

Use this function in the error handler to obtain information about the last error code and which component generated it. In addition if an error string generator function was provided during error generation, this function may return a text string, describing the error in more detail.

Parameters

  error | Pointer to integer, where the error code is written
  scope | Pointer to integer, where the error scope (module that was generating the error is written)
  str | Pointer to string buffer, where error message is written. If no string information is required, pass NULL pointer.
  bufSize | Size of the string buffer, pass 0 if not used

Returns
  Value passed in str

## ◆ HAL_GetErrorString()

char const* HAL_GetErrorString | ( | int | error,
|  | int | scope,
|  | char * | str,
|  | int | bufSize
| ) |  |

Error string generator for HAL-scoped errors.

This function generates error information for HAL scoped errors. Usually user code does not need to use this function directly.

Parameters

  error | Error code for which error information is to be returned
  scope | Error scope for which error information is to be returned
  str | Pointer to string buffer, where error message is written
  bufSize | Size of the string buffer

Returns
  Value passed in str

## ◆ HAL_HandleError()

void HAL_HandleError | ( | int | errorCode,
|  | void const * | context
| ) |  |

Error handling function.

The implementation of this function defines the behavior of the application code when an error occurs during execution.

Parameters

  errorCode | code of the error to be handled
  context | additional context information

## ◆ HAL_Init()

int HAL_Init | ( | Interface_t * | hal | ) |

Initialize hardware and populate Interface_t object.

Any implementation must initialize those members of the Interface_t object that are required by the sensor being operated with pointers to functions that implement the behavior as specified in the Interface_t member documentation.

Parameters

  hal | pointer to Interface_t object to be initialized

Returns
  error code

Return values

  0 | on success
  !=0 | in case of error

## ◆ HAL_SetError()

int HAL_SetError | ( | int | error,
|  | int | scope,
|  | ErrorStringGenerator_t | errStrFn
| ) |  |

Function storing error information.

The sensor interface has different components which may generate error conditions. To keep the sensor interface as simple as possible, this function is called in case of an error. The return value of this function will be returned as error code of the function in which an error has occurred.

Internally, this function stores the error code and the scope of the error (that is which module was generating the error) in a data structure. For all errors which do not have the scope esSensor, this function will return the generic error code ecHALError. Error codes generated by the sensor are returned directly.

It is possible to pass an error string generator function along with the error information. If this function is provided, the error handler can query an error string, providing more meaningful error information.

Parameters

  error | An error code
  scope | The scope of the error (integer identifying a module)
  errStrFn | Optional function pointer that can decode generate a meaningful message for the error code. Pass NULL if not used.

## ◆ zmod4xxx_init()

int zmod4xxx_init | ( | zmod4xxx_dev_t * | dev,
|  | Interface_t * | hal
| ) |  |

Find the sensor and initialize hal specific data

If example code is ported to the customer platform, this function must be re-implemented. The function must assign the zmod4xxx_dev_t::read, zmod4xxx_dev_t::write and zmod4xxx_dev_t::delay_ms members of dev.

Parameters

  [in] | dev | pointer to the sensor object
  [in] | hal | pointer to the hal interface object

Returns
  error code

Return values

  0 | on success
  !=0 | hardware specific error code