diff --git a/README.md b/README.md index 43af15e..73bf425 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,11 @@ # IS31FL3236 STM32 HAL Driver -NOTE: This repository is still in the beta phase, so some parts are not finished yet. + This project is a driver for the IS31FL3236 IC from ISSI for use with the STM32 and the HAL library from ST. The whole driver is designed to work with the HAL / Cube(MX) library of ST, but can be portet to other hardwares. + ## Implementation -This driver can be implemented in to any STM32 project built upon the HAL library of ST. More information on the implementation can be found on the GitHub wiki of this repository. + +This driver can be implemented in to any STM32 project built upon the HAL library of ST. More information on the implementation can be found on the [GitHub-Wiki](https://github.com/berndoJ/IS31FL3236_STM32_HAL_Driver/wiki) of this repository. + ## Contributors + This driver was created by Johannes Berndorfer (berndoJ) in April 2019. diff --git a/doc/Home.md b/doc/Home.md index 2f13b54..8f02f52 100644 --- a/doc/Home.md +++ b/doc/Home.md @@ -8,4 +8,6 @@ The IS31FL3236 chip is a general purpose digital LED driver chip which can be co ## How? -To get started using this library refer to the [Getting Started](https://github.com/berndoJ/IS31FL3236_STM32_HAL_Driver/wiki/Getting-Started) page. A further description on how to use this library can be found at the [Using the IS31FL3236 STM32 HAL Driver Library](https://github.com/berndoJ/IS31FL3236_STM32_HAL_Driver/wiki/Using-the-IS31FL3236-STM32-HAL-Driver-Library) wiki-page. \ No newline at end of file +To get started using this library refer to the [Getting Started](https://github.com/berndoJ/IS31FL3236_STM32_HAL_Driver/wiki/Getting-Started) page. A further description on how to use this library can be found at the [Using the IS31FL3236 STM32 HAL Driver Library](https://github.com/berndoJ/IS31FL3236_STM32_HAL_Driver/wiki/Using-the-IS31FL3236-STM32-HAL-Driver-Library) wiki-page. + +If you are experiencing any issues, feel free to open a new issue on the GitHub. \ No newline at end of file diff --git a/doc/IS31FL3236_SetSoftwareShutdown Function.md b/doc/IS31FL3236_SetSoftwareShutdown Function.md new file mode 100644 index 0000000..f5df400 --- /dev/null +++ b/doc/IS31FL3236_SetSoftwareShutdown Function.md @@ -0,0 +1,24 @@ +### Declaration + +```c +void IS31FL3236_SetSoftwareShutdown(IS31FL3236_HandleTypeDef* handle, uint8_t software_shutdown_mode); +``` + +### Parameters + +- **handle** [`IS31FL3236_HandleTypeDef*`]: The handle instance of the IS31FL3236 chip. +- **software_shutdown_mode** [`uint8_t`]: The new software shutdown mode the chip should enter. Use the +definitions `IS31FL3236_SOFTWARE_SHUTDOWN_ENABLED` and `IS31FL3236_SOFTWARE_SHUTDOWN_DISABLED` to specify +the shutdown mode. + +### Description + +This function sets the IS31FL3236 chip into the given software shutdown mode. For further +information about shutdown modes refer to the datasheet. ([Link to IS31FL3236 Datasheet](http://www.issi.com/WW/pdf/31FL3236.pdf) + +### Example + +```c +// Set the chip into software enabled mode (disable shutdown mode) +IS31FL3236_SetSoftwareShutdown(p_hIS31FL3236, IS31FL3236_SOFTWARE_SHUTDOWN_DISABLED); +``` \ No newline at end of file diff --git a/doc/IS31FL3236_WriteGlobalLEDControl Function.md b/doc/IS31FL3236_WriteGlobalLEDControl Function.md new file mode 100644 index 0000000..c173fa0 --- /dev/null +++ b/doc/IS31FL3236_WriteGlobalLEDControl Function.md @@ -0,0 +1,27 @@ +### Declaration + +```c +void IS31FL3236_WriteGlobalLEDControl(IS31FL3236_HandleTypeDef* handle, uint8_t led_current_setting, uint8_t led_state); +``` + +### Parameters + +- **handle** [`IS31FL3236_HandleTypeDef*`]: The handle instance of the IS31FL3236 chip. +- **led_current_setting** [`uint8_t`]: The new LED current setting of all channels. Use the definitions `IS31FL3236_LED_CURRENT_MAX`, `IS31FL3236_LED_CURRENT_MAX_DIV_2`, `IS31FL3236_LED_CURRENT_MAX_DIV_3`, `IS31FL3236_LED_CURRENT_MAX_DIV_4` to specify the current mode. +- **led_state** [`uint8_t`]: The new LED state of all channels. Use the definitions `IS31FL3236_LED_STATE_OFF` and `IS31FL3236_LED_STATE_ON` to specify the LED mode. + +### Description + +This function is identical to the `IS31FL3236_WriteLEDControl` function, but insted of changing +the LED current control and state of one channel, it changes these values globally. This function +uses a special harware command (see datasheet), thus it is faster than looping over all channels +and changing the values seperately. + +### Example + +```c +// Set the basic global LED current mode and state settings. (Turn on all channels to the max. current) +IS31FL3236_WriteGlobalLEDControl(p_hIS31FL3236, IS31FL3236_LED_CURRENT_MAX, IS31FL3236_LED_STATE_ON); +// Send an update command to the chip. +IS31FL3236_Update(p_hIS31FL3236); +``` \ No newline at end of file diff --git a/doc/IS31FL3236_WriteLEDControl Function.md b/doc/IS31FL3236_WriteLEDControl Function.md new file mode 100644 index 0000000..a02ef30 --- /dev/null +++ b/doc/IS31FL3236_WriteLEDControl Function.md @@ -0,0 +1,27 @@ +### Declaration + +```c +void IS31FL3236_WriteLEDControl(IS31FL3236_HandleTypeDef* handle, uint8_t channel, uint8_t led_current_setting, uint8_t led_state); +``` + +### Parameters + +- **handle** [`IS31FL3236_HandleTypeDef*`]: The handle instance of the IS31FL3236 chip. +- **channel** [`uint8_t`]: The channel number (0 - 35) to change the PWM value of. +- **led_current_setting** [`uint8_t`]: The new LED current setting of the specified channel. Use the definitions `IS31FL3236_LED_CURRENT_MAX`, `IS31FL3236_LED_CURRENT_MAX_DIV_2`, `IS31FL3236_LED_CURRENT_MAX_DIV_3`, `IS31FL3236_LED_CURRENT_MAX_DIV_4` to specify the current mode of the channel. +- **led_state** [`uint8_t`]: The new LED state of the specified channel. Use the definitions `IS31FL3236_LED_STATE_OFF` and `IS31FL3236_LED_STATE_ON` to specify the LED mode. + +### Description + +This function sets the LED current mode and state of a specified channel. Further +information about the LED current mode and state can be found in the manufacturer's +datasheet of the IS31FL3236 IC. ([Link to IS31FL3236 Datasheet](http://www.issi.com/WW/pdf/31FL3236.pdf) + +### Example + +```c +// Set the LED current mode and state. +IS31FL3236_WriteLEDControl(p_hIS31FL3236, 3, IS31FL3236_LED_CURRENT_MAX_DIV_2, IS31FL3236_LED_STATE_ON); +// Send the chip and update command. +IS31FL3236_Update(p_hIS31FL3236); +``` \ No newline at end of file diff --git a/doc/IS31FL3236_WritePWM Function.md b/doc/IS31FL3236_WritePWM Function.md index 55c3f6d..de87f82 100644 --- a/doc/IS31FL3236_WritePWM Function.md +++ b/doc/IS31FL3236_WritePWM Function.md @@ -5,11 +5,22 @@ void IS31FL3236_WritePWM(IS31FL3236_HandleTypeDef* handle, uint8_t channel, uint ``` ### Parameters + - **handle** [`IS31FL3236_HandleTypeDef*`]: The handle instance of the IS31FL3236 chip. - **channel** [`uint8_t`]: The channel number (0 - 35) to change the PWM value of. - **pwm_value** [`uint8_t`]: The new PWM-value to write to the given channel. ### Description + This function changes the PWM value of a given LED channel (0 - 35). The function `IS31FL3236_Update` has to be called afterwards to update the LED -channels to the new value. \ No newline at end of file +channels to the new value. + +### Example + +```c +// Set the PWM value of channel (ID) 8 to 200. +IS31FL3236_WritePWM(p_hIS31FL3236, 8, 200); +// Send the chip an update command. +IS31FL3236_Update(p_hIS31FL3236); +``` \ No newline at end of file diff --git a/doc/IS31FL3236_WriteRGBPWM Function.md b/doc/IS31FL3236_WriteRGBPWM Function.md index 85bbf91..0b9945d 100644 --- a/doc/IS31FL3236_WriteRGBPWM Function.md +++ b/doc/IS31FL3236_WriteRGBPWM Function.md @@ -16,4 +16,13 @@ void IS31FL3236_WriteRGBPWM(IS31FL3236_HandleTypeDef* handle, uint8_t rgb_channe This function changes the color of a given RGB LED channel (0 - 11). The function `IS31FL3236_Update` has to be called afterwards to update the LED -channels to the new value. \ No newline at end of file +channels to the new value. + +### Example + +```c +// Set the color of RGB channel 0 to #FF00FF (Violet / Purple) +IS31FL3236_WriteRGBPWM(p_hIS31FL3236, 0, 0xFF, 0x00, 0xFF); +// Send the chip an update command. +IS31FL3236_Update(p_hIS31FL3236); +``` \ No newline at end of file diff --git a/doc/IS31FL3236_WriteRegister Function.md b/doc/IS31FL3236_WriteRegister Function.md new file mode 100644 index 0000000..21ea8d8 --- /dev/null +++ b/doc/IS31FL3236_WriteRegister Function.md @@ -0,0 +1,32 @@ +### Declaration + +```c +void IS31FL3236_WriteRegister(IS31FL3236_HandleTypeDef* handle, uint8_t register_address, uint8_t value); +``` + +### Parameters + +- **handle** [`IS31FL3236_HandleTypeDef*`]: The handle instance of the IS31FL3236 chip. +- **register_address** [`uint8_t`]: The address of the register on the IS31FL3236 chip to write to. The register addresses can be looked up in the datasheet of the IS31FL3236 or can be retrieved by using the included definitions (see Register Address Definitions). + +### Description + +This function can be used to manually write to an internal register on the IS31FL3236 chip. + +### Register Address Definitions + +This library contains a collection of definitions that can be used to retrieve the addresses of the IS31FL3236's internal registers. The following list contains all available register address definitions. + +- `IS31FL3236_REGISTER_SHUTDOWN` - Shutdown Register - `0x00` +- `IS31FL3236_REGISTER_PWM` - First PWM value register - `0x01` +- `IS31FL3236_REGISTER_LED_CTRL` - First LED control register - `0x26` +- `IS31FL3236_REGISTER_UPDATE` - Update initiation register - `0x25` +- `IS31FL3236_REGISTER_GLOBAL_CTRL` - Global LED control register - `0x4a` +- `IS31FL3236_REGISTER_RESET` - Reset initiation register - `0x4f` + +### Example + +```c +// Write 0x00 to the update register - similar to IS31FL3236_Update function. +IS31FL3236_WriteRegister(p_hIS31FL3236, IS31FL3236_REGISTER_UPDATE, 0x00); +``` \ No newline at end of file diff --git a/inc/is31fl3236_driver.h b/inc/is31fl3236_driver.h index 09aeaba..d136db6 100644 --- a/inc/is31fl3236_driver.h +++ b/inc/is31fl3236_driver.h @@ -31,6 +31,8 @@ extern "C" #include // Include ST's HAL library for the STM32. The correct library for the platform has to be chosen. +// Definitions of values for updating and changing settings of the IC. These values have been retrieved from the IS31FL3236's datasheet. + #define IS31FL3236_I2C_AD_TO_GND 0x00 #define IS31FL3236_I2C_AD_TO_SCL 0x02 #define IS31FL3236_I2C_AD_TO_SDA 0x04 diff --git a/raw_documentation.txt b/raw_documentation.txt deleted file mode 100644 index 79e8770..0000000 --- a/raw_documentation.txt +++ /dev/null @@ -1,114 +0,0 @@ -OLD VERSION ---------------------------------------------------------------------------- - - -IS31FL3236_STM32_HAL_Driver Project Documentation -------------------------------------------------- - -IS31FL3236_STM32_HAL_Driver is an driver implementation for the CubeMX HAL environment -running on the STM32 family of microcontroller devices. The purpose of this software -is to provide a basic hardware abstraction level for the IS31FL3236 LED-Driver chip. - -The library itself is written in C and can be used in C as well as C++ STM32 CubeMX -projects. - - -Including the library ---------------------- - -In order to use this library, is31fl3236_driver.h has to be included in the project. -This file contains all necessary declarations in order to use the library correctly. - - -Using the IS31FL3236_STM32_HAL_Driver library ---------------------------------------------- - -Initialisation of a new device handle -- - - - - - - - - - - - - - - - - - - - -In order to support multiple IS31FL3236 devices on the same STM32 microcontroller, -this library uses seperately initialised handles to refer to a specific IS31FL3236 -chip. All necessary hardware information, such as the I2C bus, SDN pin, etc., has -to be provided in order for the initialisation to be complete. - -The initialisation of a new IS31FL3236 is shown by the following piece of example -code. - - -// Handle pointer for possible global access: -IS31FL3236_HandleTypeDef* ptr_h_led_drvr_foo; - - - -IS31FL3236_HandleTypeDef h_led_drvr_foo; -h_led_drvr_foo.I2C_Bus = hi2c1; -h_led_drvr_foo.I2C_Device_Address = IS31FL3236_GET_I2C_ADDR(IS31FL3236_I2C_AD_TO_GND); -h_led_drvr_foo.I2C_Transmit_Timeout_Milliseconds = 10; // 10ms is default. -h_led_drvr_foo.Chip_Enable_Signal_Port = GPIOA; -h_led_drvr_foo.Chip_Enable_Signal_Pin = GPIO_PIN_10; - -// Optional [ -h_led_drvr_foo.RGB_Mode_Color_1 = IS31FL3236_RGB_CONFIG_RED; -h_led_drvr_foo.RGB_Mode_Color_2 = IS31FL3236_RGB_CONFIG_GREEN; -h_led_drvr_foo.RGB_Mode_Color_3 = IS31FL3236_RGB_CONFIG_BLUE; -// ] - -ptr_h_led_drvr_foo = &h_led_drvr_foo; // Store the pointer to the handle in a (global) variable for future access in other functions. - -IS31FL3236_Init(ptr_h_led_drvr_foo); // Init the handle. - - -Note that IS31FL3236_Init has to be called with a handle before the -handle gets used by any other function. - -The IS31FL3236_Init performes a device reset, disables the software -device shutdown and enables the IS31FL3236 chip via the enable/SDB signal. - -After the initialisation the driver is operational and can be used. - - -Update cycles of the IS31Fl3236 -- - - - - - - - - - - - - - - - - -In order to allow instant switching from one configuration to another, the -IS31FL3236 chip latches the recieved data only when an update command is sent -to the device via the I2C bus. - -By calling IS31FL3236_Update the device latches all recieved data -to the led control circuitry. - - -Reset, software shutdown and chip enable -- - - - - - - - - - - - - - - - - - - - - - -By calling IS31FL3236_Reset the device gets reset. What a reset -command does can be read in the device datasheet of the IS31Fl3236. - -The IS31FL3236_SetSoftwareShutdown sets the software shutdown mode -of the deivce. - -IS31FL3236_SetChipEnable controlls the hardware chip enable (SDB) -signal of the chip. - - -Random LED ON/OFF example -------------------------- - -Random RGB LED example ----------------------- - -IS31FL3236_WritePWM Function ----------------------------- - -Declaration: -void IS31FL3236_WritePWM(IS31FL3236_HandleTypeDef* handle, uint8_t channel, uint8_t pwm_value); - -Parameters: -- handle [IS31FL3236_HandleTypeDef*]: The handle instance of the IS31FL3236 chip. -- channel [uint8_t]: The channel number (0 - 35) to change the PWM value of. -- pwm_value [uint8_t]: The new PWM-value to write to the given channel. - -Description: -This function changes the PWM value of a given LED channel (0 - 35). The function -IS31FL3236_Update has to be called afterwards to update the LED -channels to the new value. \ No newline at end of file