ST AN3108 Application note
AN3108
Application note
STLM75 firmware library for the STM32F10x
Introduction
This application note describes the firmware library implementing the STLM75 interface for
the STM32F10xxx (STM32F101x, STM32F103x, STM32F105x, STM32F107x)
microcontroller.
This library is a firmware package which contains a collection of routines, data structures
and macros covering the features of the STLM75 temperature sensor device. The firmware
library allows the STLM75 sensor to be used in the user application without the need for an
in-depth study of STLM75 registers and I
the firmware library saves significant time which would otherwise be spent in coding, while
reducing the application development and integration costs.
The firmware library source code is developed in 'Strict ANSI-C' (relaxed ANSI-C for the
example application). Writing the whole library in 'Strict ANSI-C' makes it independent from
the software toolchain. In addition, the firmware architecture is developed in separate layers
and the HAL (hardware abstraction layer) makes it independent from the microcontroller
used in the final application.
2
C read/write operation steps. As a result, using
Even though the firmware library source code is developed in 'ANSI-C', the code
architecture follows an OOP (object oriented programming) approach.
Section 1 describes document and library rules.
Section 2 highlights the features of the STLM75 sensor and explains its hardware interface
with a master device microcontroller (STM32 in this case).
Section 3 and 4 highlight the features of the firmware library and describe its architecture
and its exported APIs (application programming interfaces) in detail.
Section 5 contains an example application source code describing how to configure and use
the library.
October 2010 Doc ID 16793 Rev 1 1/44
www.st.com
Contents AN3108
Contents
1 Document and library rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1 Acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2 STLM75 temperature sensor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.1 Sensor introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.2 Interfacing the sensor with the microcontroller . . . . . . . . . . . . . . . . . . . . . . 6
3 STLM75 library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.2 Library package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.3 Library architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.3.1 API layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.3.2 HAL layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
4 STLM75 library firmware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.1 API layer firmware overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.2 HAL Layer firmware overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
4.2.1 HAL types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
4.2.2 HAL functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
5 Example application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
5.1 main.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
6 References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
7 Revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
2/44 Doc ID 16793 Rev 1
AN3108 List of tables
List of tables
Table 1. List of abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Table 2. Signal names and pin descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Table 3. Function description format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Table 4. NewTempSensor API function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Table 5. DelTempSensor API function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Table 6. Init API function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Table 7. Reset API function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Table 8. SetI2C_Settings API function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Table 9. SetSignals. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Table 10. GetSignals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Table 11. SetRegister . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Table 12. GetRegister. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Table 13. SetConfiguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Table 14. GetConfiguration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Table 15. GetTemperature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Table 16. SetTempHysteresis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Table 17. GetTempHysteresis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Table 18. SetTempOverLimit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Table 19. GetTemperatureOverLimit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Table 20. TS_ConfigSignal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Table 21. TS_InitI2C_Peripheral . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Table 22. TS_ResetI2C_Peripheral . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Table 23. TS_CheckEventWithTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Table 24. TS_FillDataFromRegister . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Table 25. TS_FillRegisterFromData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Table 26. TS_SetPointerRegister . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Table 27. Document revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Doc ID 16793 Rev 1 3/44
List of figures AN3108
List of figures
Figure 1. Logic diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Figure 2. Typical 2-wire interface connection diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Figure 3. Firmware library project files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Figure 4. Firmware library architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Figure 5. Firmware library API and types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Figure 6. Application project files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
4/44 Doc ID 16793 Rev 1
AN3108 Document and library rules
1 Document and library rules
This document uses the conventions described in the sections below.
1.1 Acronyms
The following table lists the acronyms used in this document.
Table 1. List of abbreviations
Acronym Meaning
API Application programming interface
HAL Hardware abstraction layer
MCU Microcontroller unit
I2C Inter-integrated circuit
OOP Object oriented programming
Doc ID 16793 Rev 1 5/44
STLM75 temperature sensor AN3108
2 STLM75 temperature sensor
2.1 Sensor introduction
The STLM75 is a high-precision digital CMOS temperature sensor IC with a sigma-delta
temperature-to-digital converter and an I
2
C-compatible serial digital interface. It is targeted
at general applications such as personal computers, system thermal management,
electronics equipment, and industrial controllers, and is packaged in the industry standard
8-lead TSSOP and SO8 packages. The device contains a band-gap temperature sensor
and 9-bit ADC which monitor and digitize the temperature to a resolution up to 0.5 °C. The
STLM75 is typically accurate to ±3°C - max over the full temperature measurement range of
-55 °C to 125 °C with ±2 °C accuracy in the -25 °C to + 100 °C range (max). The STLM75 is
factory-calibrated and requires no external components to measure temperature.
Refer to the STLM75 (Digital temperature sensor and thermal watchdog) datasheet for more
information.
2.2 Interfacing the sensor with the microcontroller
The STLM75 has a simple 2-wire I2C-compatible digital serial interface which allows the
user to access the data in the temperature register at any time. It communicates via the
serial interface with a master controller which operates at speeds up to 400 kHz. Three pins
(A0, A1, and A2) are available for address selection, and enable the user to connect up to 8
devices on the same bus without address conflicts. In addition, the serial interface gives the
user easy access to all STLM75 registers to customize the operation of the device.
Figure 2 shows how the SMT32F10xxx microcontroller (master device) must be connected
to the STLM75 device.
Refer to the STLM75 datasheet for more information.
Figure 1. Logic diagram
3$!
3#,
!
!
!
Note: SDA and OS/INT are open drain.
6
$$
34,-
'.$
/3).4
!-V
6/44 Doc ID 16793 Rev 1
AN3108 STLM75 temperature sensor
Table 2. Signal names and pin descriptions
Pin Sym Type/direction Description
1 SDA Input/output Serial data input/output
2 SCL Input Serial clock input
3 OS/INT Output Over-limit signal/interrupt alert output
4 GND Supply ground Ground
5A
6A
7A
8V
2
1
0
DD
Input Address2 input
Input Address1 input
Input Address0 input
Supply power Supply voltage (2.7 V to 5.5 V)
Figure 2. Typical 2-wire interface connection diagram
0ULLUP
6
$$
½ K½
K
K½
0ULLUP
6
$$
34,-
6
$$
6
$$
½ &
/3).4
!
!
!
3$!
Note: SDA and OS/INT are open drain
3#,
'.$
-ASTER
$EVICE
)#!DDRESS!!!
!-V
Doc ID 16793 Rev 1 7/44
STLM75 library AN3108
3 STLM75 library
3.1 Introduction
The STLM75 firmware library is fully developed in 'Strict ANSI-C' following an OOP
approach. This means the final application using this library uses an instance of a
temperature sensor object (TempSensor), and uses it according to its public methods and
properties. The TempSensor is a structure containing public properties (data fields) and
methods (functions pointers). The OOP encapsulation feature is assured.
The final application can create more than one TempSensor instance, and each instance
can be matched with a different STLM75 temperature sensor assembled on the board.
Therefore, the same library can be used to manage more temperature sensors
simultaneously without communication and data conflict problems.
The library may be included in the final application as a library file (STLM75.a) and used as
a black box through its exported public API, or can be included in the final application as
source files (.c and .h), if the user wants to debug the library itself, or if it’s necessary to
change the HAL functions in order to port the library on an alternative microcontroller to the
STM32F10xxx.
3.2 Library package
The library was developed using the IAR EWARM 5.20 and the related workspace/project
files are included in the delivered package. As all the firmware is written in 'Strict ANSI-C',
the library porting on another toolset doesn't require any change in the library.
The library folder contains all the subdirectories and files that make up the core of the
library:
● The included sub-folder contains the firmware library header files. They don't need to
be modified by the user:
– TempSensorObj.h: API layer file; this contains the Temperature Sensor Object
structure description in terms of methods and properties; The API functions are
declared in this file.
– TempSensorTypes.h: API layer file; this contains all the defined types used by
TempSensorObj.xxx files and related to the STLM75 temperature sensor.
– TempSensorHal.h: HAL layer file; this contains all the Temperature Sensor
functions declaration whose implementation depends on the MCU used (STM32
for this delivery). The final user should change these files in order to reuse this
STLM75 library with other microcontrollers
– TempSensorHalTypes.h HAL layer file; this contains all the Temperature Sensor
types mapped on the used MCU library types (STM32 for this delivery). The final
8/44 Doc ID 16793 Rev 1
AN3108 STLM75 library
user should change this type mapping in order to reuse this STLM75 library with
other microcontrollers
● The source sub-folder contains the firmware library source files. They don't need to be
modified by the user:
– TempSensorObj.c: API layer file; this contains the exported public API (Application
Programming Interface) and the related private internal functions. No direct
reference to the Hardware and Micro firmware library occur in this file.
– TempSensorHal.c: HAL layer file; this contains all the temperature sensor
functions implementation whose source code depends on the MCU used (STM32
for this delivery). The final user should change these file in order to reuse this
STLM75 library with other microcontrollers
– The STM32_Include sub-folder contains the STM32F10xxxV2.0.3 firmware library
included files. If the final user wants to use another microcontroller library version,
replace this folder and check the HAL types and the microcontroller library function
calls inside the HAL layer files (TempSensorHal.h, TempSensorHalTypes.h,
TempSensorHal.c)
● EWARMv5 sub-folder contains the IAR EWARM 5.20 workspace and project files:
– STLM75_Lib.eww: The IAR workspace file
– STLM75_Lib.ewp: The IAR project file
Figure 3. Firmware library project files
3.3 Library architecture
The library architecture is devised and developed in two separate layers:
● API layer
● HAL layer
This layer architecture improves the code reusability splitting the application programming
interface code (fully portable and reusable) from the hardware abstraction layer code
(hardware dependent and written onto the STM32F10xxx libraries).
3.3.1 API layer
The application programming interface layer allows the final application to use the library as
a black-box. The library firmware encapsulation feature and exported API allow full control of
Doc ID 16793 Rev 1 9/44
STLM75 library AN3108
the STLM75 temperature sensor without the need of an in-depth study of sensor registers
2
and I
C read/write operation steps.
The API layer includes the following files:
● TempSensorObj.h
● TempSensorTypes.h
● TempSensorObj.c;
See Section 4.1 for a more detailed description.
3.3.2 HAL layer
The hardware abstraction layer is directly built on the specific microcontroller firmware
library and allows the built-upon layers, like the API layer, to implement its functions without
the need of an in-depth study of the microcontroller used. This improves the library code
reusability and guarantees easy portability on other microcontrollers.
The HAL layer includes the following files:
● TempSensorHal.h
● TempSensorHalTypes.h
● TempSensorHal.c
See Section 4.2 for a more detailed description.
Figure 4. Firmware library architecture
10/44 Doc ID 16793 Rev 1
AN3108 STLM75 library firmware
4 STLM75 library firmware
This section describes the API and HAL layer implementation. Each library firmware
function is described in detail. API and HAL layer functions are fully described. An example
of how to use API functions is included. No example for HAL functions is provided because
the final application should manage the STLM75 temperature sensor through the API layer
functions only, without any direct access to the HAL functions.
The functions are described in the following format:
Table 3. Function description format
Name Description
Function name The name of the peripheral function
Function prototype Prototype declaration
Behavior description Brief explanation of how the function is executed
Input parameter {x} Description of the input parameters
Output parameter {x} Description of the output parameters
Return value Value returned by the function
Required preconditions Requirements before calling the function
Called functions Other library functions called
4.1 API layer firmware overview
The application programming interface layer allows the final application to easily use the
STLM75 temperature sensor. An OOP approach is used, making it possible for the
application to create and use one or more instances of a TempSensor object.
The TempSensor structure is seen by the application as an object with encapsulate
properties and methods. All read/write operations on the temperature sensors are executed
through this object. It is an advanced structure containing:
● Properties as data fields
● Methods as functions pointers
In this way, each API function belongs to the related TempSensor object instance and more
instances, and then more temperature sensors, can be managed without any conflicts.
In addition, the library exports two public API global functions in order to create/destroy a
TempSensor structure instance:
● NewTempSensorObj function
● DelTempSensorObj function
Doc ID 16793 Rev 1 11/44
STLM75 library firmware AN3108
NewTempSensorObj API global function
Ta bl e 4 describes the NewTempSensorObj function:
Table 4. NewTempSensor API function
Name Description
Function name NewTempSensorObj
Function prototype TempSensorType* NewTempSensorObj (void)
Behavior description Create and initialize a new TempSensor object (a C structure)
Input parameter {x} None
Output parameter {x} None
Return value The created object pointer or null if the object cannot be created
Required preconditions None
Called functions No API/HAL layers functions;
Example:
TempSensorType* pObjTempSensor;
pObjTempSensor = NewTempSensorObj ();
/* Hardware Configuration: Signals: SCL, SDA, OS_INT pins */
TS_SignalsType TempSensorSignals;
...
/* Hardware Configuration: I2C pheripheral */
TS_I2C_SettingsType TempSensorI2C_Settings;
...
/* Initialize the temperature sensor according to previous Signals
and
I2C_Settings */
pObjTempSensor->Init(pObjTempSensor, &TempSensorSignals,
&TempSensorI2C_Settings);
Once a TempSensor object instance is created using the NewTempSensorObj function, the
TempSensor object itself provides all its features through its internal function pointers.
Figure 2 shows the TempSensor object properties and methods in detail, which the final
application can use to interact with the temperature sensor.
12/44 Doc ID 16793 Rev 1
AN3108 STLM75 library firmware
DelTempSensorObj API global function
Ta bl e 5 describes the DelTempSensorObj function:
Table 5. DelTempSensor API function
Name Description
Function name DelTempSensorObj
Function prototype TS_ErrStatus DelTempSensorObj (TempSensorType** ppTempSensor)
Behavior description
Input parameter {x} ppTempSensor - Object pointer
Output parameter {x} None
Return value TS_OK if successful, TS_ERROR otherwise
Required preconditions NewTempSensorObj must have been called before
Called functions No API/HAL layers functions;
Destroy the Object internal members and free the memory allocated when
NewTempSensorObj function is called.
Example:
TempSensorType* pObjTempSensor;
TS_ErrStatus errStatus;
...
errStatus = DelTempSensorObj(pTempSensorObj);
Figure 5. Firmware library API and types
Doc ID 16793 Rev 1 13/44
STLM75 library firmware AN3108
TempSensorObj API types/properties/functions
This section describes the TempSensor structure, all its exported API functions and all the
defined types. See Figure 2.
Below you can find a description of the defined types used by the TempSensor object
source code and a description of its properties and methods. Except for TempSensorType,
all API layer types are defined in the TempSensorTypes.h file.
TempSensorType type
The TempSensorType is defined in the following TempSensorObj.h file. The final
TempSensor object is an instance of this defined structure.
The following described structure type can be considered as an OOP-class including private
and public properties and public methods.
All the structure fields with a prefix name of 'm_' can be considered as private properties.
This means these structure fields must not be directly accessed by the final application and
Getxxx methods should be used instead. Clearly the final application could access these
private members, but it should NEVER do so.
The final application must interact with this library using the following public properties and
methods only, as described in Figure 2 and in the following sections.
#define TEMP_SENSOR_OBJ /* Temperature Sensor definition */ \
/* */ \
/* PRIVATE PROPERTIES */ \
TS_u8 m_Configuration; \
TS_TemperatureType m_Temperature; \
TS_TemperatureType m_TempHysteresis; \
TS_TemperatureType m_TempOverLimit; \
TS_RegistersType m_Registers; \
TS_I2C_SettingsType m_I2C_Settings; \
/* */ \
/* PUBLIC PROPERTIES */ \
TS_SignalsType Signals; /* The Micro/STLM75 signals */ \
TS_u32 TimeoutTicks; /* Timeout in ticks */ \
/* */ \
/* PUBLIC METHODS */ \
TS_ErrStatus (*Init) (TempSensorType*); \
TS_ErrStatus (*Reset) (TempSensorType*); \
TS_ErrStatus (*SetI2C_Settings) (TempSensorType*,
TS_I2C_SettingsType* pI2C_Settings); \
TS_ErrStatus (*SetSignals) (TempSensorType*,
TS_SignalsType* pSignals); \
14/44 Doc ID 16793 Rev 1
Loading...