Add support for setting brightness (#121)

* Fix comment of PreChargePeriod

* Messy implementation of brightness change

* Add CHANGELOG entry

* Commit suggested changes

Co-authored-by: James Waples <[email protected]>

* Remove change_property

* Fix alignment and comments

* Implement Default and use it when initializing

* Run cargo fmt

* Add example

* Add a note to precharge, assert its value before sending command

* Implement suggested changes

Co-authored-by: James Waples <[email protected]>

* Update src/command.rs, fix comment

Co-authored-by: James Waples <[email protected]>

* Run cargo fmt

* Also rename method where used...

Co-authored-by: Dániel Buga <[email protected]>
Co-authored-by: James Waples <[email protected]>

Author: 3 people

CHANGELOG.md

@@ -8,6 +8,7 @@
 
 ### Added
 
+- [#121](https://github.com/jamwaffles/ssd1306/pull/121) Added brightness control with the `set_brightness()` method.
 - [#118](https://github.com/jamwaffles/ssd1306/pull/118) `DisplayModeTrait::into_properties()` new method that consumes the driver and returns the `DisplayProperties`
 
 ### Changed

examples/rtfm_brightness.rs

@@ -0,0 +1,192 @@
+//! Cycle the screen brightness through 5 predefined brightness levels when the "DVD" logo hits one
+//! of the sides of the display.
+//!
+//! For best results, run with the `--release` flag.
+
+#![no_std]
+#![no_main]
+
+use core::convert::TryFrom;
+use display_interface_spi::SPIInterfaceNoCS;
+use embedded_graphics::{
+    geometry::Point, image::Image, pixelcolor::BinaryColor, prelude::*, primitives::Rectangle,
+};
+use panic_halt as _;
+use rtfm::app;
+use ssd1306::{prelude::*, Builder};
+use stm32f1xx_hal::{
+    delay::Delay,
+    gpio,
+    pac::{self, SPI1},
+    prelude::*,
+    spi::{self, Mode, Phase, Polarity, Spi},
+    timer::{CountDownTimer, Event, Timer},
+};
+use tinybmp::Bmp;
+
+type Display = ssd1306::mode::graphics::GraphicsMode<
+    SPIInterfaceNoCS<
+        spi::Spi<
+            SPI1,
+            spi::Spi1NoRemap,
+            (
+                gpio::gpioa::PA5<gpio::Alternate<gpio::PushPull>>,
+                gpio::gpioa::PA6<gpio::Input<gpio::Floating>>,
+                gpio::gpioa::PA7<gpio::Alternate<gpio::PushPull>>,
+            ),
+        >,
+        gpio::gpiob::PB1<gpio::Output<gpio::PushPull>>,
+    >,
+>;
+
+#[app(device = stm32f1xx_hal::pac, peripherals = true)]
+const APP: () = {
+    struct Resources {
+        display: Display,
+        timer: CountDownTimer<pac::TIM1>,
+        top_left: Point,
+        velocity: Point,
+        bmp: Bmp<'static>,
+        brightness: Brightness,
+    }
+
+    #[init]
+    fn init(cx: init::Context) -> init::LateResources {
+        let dp = cx.device;
+        let core = cx.core;
+
+        let mut flash = dp.FLASH.constrain();
+        let mut rcc = dp.RCC.constrain();
+
+        let clocks = rcc
+            .cfgr
+            .use_hse(8.mhz())
+            .sysclk(72.mhz())
+            .pclk1(36.mhz())
+            .freeze(&mut flash.acr);
+
+        let mut afio = dp.AFIO.constrain(&mut rcc.apb2);
+
+        let mut gpiob = dp.GPIOB.split(&mut rcc.apb2);
+        let mut gpioa = dp.GPIOA.split(&mut rcc.apb2);
+
+        // SPI1
+        let sck = gpioa.pa5.into_alternate_push_pull(&mut gpioa.crl);
+        let miso = gpioa.pa6;
+        let mosi = gpioa.pa7.into_alternate_push_pull(&mut gpioa.crl);
+
+        let mut delay = Delay::new(core.SYST, clocks);
+
+        let mut rst = gpiob.pb0.into_push_pull_output(&mut gpiob.crl);
+        let dc = gpiob.pb1.into_push_pull_output(&mut gpiob.crl);
+
+        let spi = Spi::spi1(
+            dp.SPI1,
+            (sck, miso, mosi),
+            &mut afio.mapr,
+            Mode {
+                polarity: Polarity::IdleLow,
+                phase: Phase::CaptureOnFirstTransition,
+            },
+            8.mhz(),
+            clocks,
+            &mut rcc.apb2,
+        );
+
+        let interface = display_interface_spi::SPIInterfaceNoCS::new(spi, dc);
+        let mut display: GraphicsMode<_> = Builder::new()
+            .with_rotation(DisplayRotation::Rotate180)
+            .connect(interface)
+            .into();
+
+        display.reset(&mut rst, &mut delay).unwrap();
+        display.init().unwrap();
+
+        // Update framerate
+        let fps = 20;
+
+        let mut timer = Timer::tim1(dp.TIM1, &clocks, &mut rcc.apb2).start_count_down(fps.hz());
+
+        timer.listen(Event::Update);
+
+        let bmp = Bmp::from_slice(include_bytes!("dvd.bmp")).unwrap();
+
+        // Init the static resources to use them later through RTFM
+        init::LateResources {
+            timer,
+            display,
+            top_left: Point::new(5, 3),
+            velocity: Point::new(1, 1),
+            bmp,
+            brightness: Brightness::default(),
+        }
+    }
+
+    #[task(binds = TIM1_UP, resources = [display, top_left, velocity, timer, bmp, brightness])]
+    fn update(cx: update::Context) {
+        let update::Resources {
+            display,
+            top_left,
+            velocity,
+            timer,
+            bmp,
+            brightness,
+            ..
+        } = cx.resources;
+
+        let bottom_right = *top_left + Point::try_from(bmp.dimensions()).unwrap();
+
+        // Erase previous image position with a filled black rectangle
+        Rectangle::new(*top_left, bottom_right)
+            .into_styled(embedded_graphics::primitive_style!(
+                fill_color = BinaryColor::Off
+            ))
+            .draw(display)
+            .unwrap();
+
+        // Check if the image collided with a screen edge
+        {
+            let mut collision = false;
+            if bottom_right.x > display.size().width as i32 || top_left.x < 0 {
+                velocity.x = -velocity.x;
+                collision = true;
+            }
+
+            if bottom_right.y > display.size().height as i32 || top_left.y < 0 {
+                velocity.y = -velocity.y;
+                collision = true;
+            }
+
+            if collision {
+                // Change the brightness
+                *brightness = match *brightness {
+                    Brightness::DIMMEST => Brightness::DIM,
+                    Brightness::DIM => Brightness::NORMAL,
+                    Brightness::NORMAL => Brightness::BRIGHT,
+                    Brightness::BRIGHT => Brightness::BRIGHTEST,
+                    Brightness::BRIGHTEST => Brightness::DIMMEST, // restart cycle
+                    _ => Brightness::NORMAL, // Brightness is not an enum, cover rest of patterns
+                };
+
+                // Send the new brightness value to the display
+                display.set_brightness(*brightness).unwrap();
+            }
+        }
+
+        // Move the image
+        *top_left += *velocity;
+
+        // Draw image at new position
+        Image::new(bmp, *top_left).draw(display).unwrap();
+
+        // Write changes to the display
+        display.flush().unwrap();
+
+        // Clears the update flag
+        timer.clear_update_interrupt_flag();
+    }
+
+    extern "C" {
+        fn EXTI0();
+    }
+};

src/brightness.rs

@@ -0,0 +1,48 @@
+//! Display brightness
+
+/// Struct that holds display brightness
+#[derive(Copy, Clone, PartialEq, Eq)]
+pub struct Brightness {
+    pub(crate) precharge: u8,
+    pub(crate) contrast: u8,
+}
+
+impl Default for Brightness {
+    fn default() -> Self {
+        Brightness::NORMAL
+    }
+}
+
+impl Brightness {
+    /// The dimmest predefined brightness level
+    pub const DIMMEST: Brightness = Brightness::custom(0x1, 0x00);
+
+    /// A dim predefined brightness level
+    pub const DIM: Brightness = Brightness::custom(0x2, 0x2F);
+
+    /// A medium predefined brightness level
+    pub const NORMAL: Brightness = Brightness::custom(0x2, 0x5F);
+
+    /// A bright predefined brightness level
+    pub const BRIGHT: Brightness = Brightness::custom(0x2, 0x9F);
+
+    /// The brightest predefined brightness level
+    pub const BRIGHTEST: Brightness = Brightness::custom(0x2, 0xFF);
+
+    /// Create a Brightness object from a precharge period and contrast pair.
+    ///
+    /// `precharge` sets the `phase 2` argument of the `0xD9 Set Pre-Charge Period` command and must
+    /// be must be between 1 and 15.
+    /// The effects of this parameter are hardware dependent. For the common 128x64 displays, values
+    /// 1 and 2 result in different brightness levels, values above 2 behave the same was as 2.
+    /// See section 10.1.17 of the SSD1306 datasheet for more information.
+    ///
+    /// `contrast` sets the value used in the `0x81 Set Contrast Control` command and must be
+    /// between 0 and 255. See section 10.1.7 of the SSD1306 datasheet for more information.
+    const fn custom(precharge: u8, contrast: u8) -> Self {
+        Self {
+            precharge,
+            contrast,
+        }
+    }
+}

src/command.rs

@@ -76,7 +76,7 @@ pub enum Command {
     /// First value is oscillator frequency, increasing with higher value
     /// Second value is divide ratio - 1
     DisplayClockDiv(u8, u8),
-    /// Set up phase 1 and 2 of precharge period. each value is from 0-63
+    /// Set up phase 1 and 2 of precharge period. Each value must be in the range 1 - 15.
     PreChargePeriod(u8, u8),
     /// Set Vcomh Deselect level
     VcomhDeselect(VcomhLevel),

src/lib.rs

@@ -142,6 +142,7 @@ pub enum Error<CommE, PinE> {
 
 extern crate embedded_hal as hal;
 
+pub mod brightness;
 pub mod builder;
 mod command;
 pub mod displayrotation;

src/mode/graphics.rs

@@ -58,7 +58,7 @@
 use display_interface::{DisplayError, WriteOnlyDataCommand};
 
 use crate::{
-    displayrotation::DisplayRotation, mode::displaymode::DisplayModeTrait,
+    brightness::Brightness, displayrotation::DisplayRotation, mode::displaymode::DisplayModeTrait,
     properties::DisplayProperties,
 };
 
@@ -228,6 +228,11 @@ where
     pub fn display_on(&mut self, on: bool) -> Result<(), DisplayError> {
         self.properties.display_on(on)
     }
+
+    /// Change the display brightness.
+    pub fn set_brightness(&mut self, brightness: Brightness) -> Result<(), DisplayError> {
+        self.properties.set_brightness(brightness)
+    }
 }
 
 #[cfg(feature = "graphics")]

src/mode/terminal.rs

@@ -28,6 +28,7 @@
 use display_interface::{DisplayError, WriteOnlyDataCommand};
 
 use crate::{
+    brightness::Brightness,
     command::AddrMode,
     displayrotation::DisplayRotation,
     displaysize::DisplaySize,
@@ -257,6 +258,11 @@ where
         self.properties.display_on(on).terminal_err()
     }
 
+    /// Change the display brightness.
+    pub fn set_brightness(&mut self, brightness: Brightness) -> Result<(), TerminalModeError> {
+        self.properties.set_brightness(brightness).terminal_err()
+    }
+
     /// Get the current cursor position, in character coordinates.
     /// This is the (column, row) that the next character will be written to.
     pub fn get_position(&self) -> Result<(u8, u8), TerminalModeError> {

src/prelude.rs

@@ -5,6 +5,7 @@ pub use display_interface_i2c::I2CInterface;
 pub use display_interface_spi::{SPIInterface, SPIInterfaceNoCS};
 
 pub use super::{
+    brightness::Brightness,
     displayrotation::DisplayRotation,
     displaysize::DisplaySize,
     mode::{displaymode::DisplayModeTrait, GraphicsMode, TerminalMode},

src/properties.rs

@@ -2,6 +2,7 @@
 
 use crate::mode::displaymode::DisplayModeTrait;
 use crate::{
+    brightness::Brightness,
     command::{AddrMode, Command, VcomhLevel},
     displayrotation::DisplayRotation,
     displaysize::DisplaySize,
@@ -83,8 +84,7 @@ where
             DisplaySize::Display64x48 => Command::ComPinConfig(true, false).send(&mut self.iface),
         }?;
 
-        Command::Contrast(0x8F).send(&mut self.iface)?;
-        Command::PreChargePeriod(0x1, 0xF).send(&mut self.iface)?;
+        self.set_brightness(Brightness::default())?;
         Command::VcomhDeselect(VcomhLevel::Auto).send(&mut self.iface)?;
         Command::AllOn(false).send(&mut self.iface)?;
         Command::Invert(false).send(&mut self.iface)?;
@@ -251,6 +251,18 @@ where
         Command::DisplayOn(on).send(&mut self.iface)
     }
 
+    /// Change the display brightness.
+    pub fn set_brightness(&mut self, brightness: Brightness) -> Result<(), DisplayError> {
+        // Should be moved to Brightness::new once conditions can be used in const functions
+        debug_assert!(
+            0 < brightness.precharge && brightness.precharge <= 15,
+            "Precharge value must be between 1 and 15"
+        );
+
+        Command::PreChargePeriod(1, brightness.precharge).send(&mut self.iface)?;
+        Command::Contrast(brightness.contrast).send(&mut self.iface)
+    }
+
     /// Change into any mode implementing DisplayModeTrait
     pub fn into<NMODE: DisplayModeTrait<DI>>(self) -> NMODE
     where