ssd1315_driver/

lib.rs

//! # SSD1315
//!
//! SSD1315 driver.
//!
//! ## Usage
//!
//! Here is an example of how to use `ssd1315`:
//!
//! ```rust
//! use ssd1315::*;
//! use embedded_graphics::{
//!     pixelcolor::BinaryColor,
//!     prelude::*,
//!     primitives::{Circle, PrimitiveStyle},
//! };
//!
//! let interface = interface::I2cDisplayInterface::new(i2c);
//! // let interface = interface::SpiDisplayInterface::new(spi, dc);
//!
//! let mut display = Ssd1315::new(interface);
//!
//! Circle::new(Point::new(0, 0), 40)
//!         .into_styled(PrimitiveStyle::with_fill(BinaryColor::On))
//!         .draw(&mut display)
//!         .unwrap();
//!
//! display.init(Default::default()).unwrap();
//! display.flush().unwrap();
//! ```
//!
//! Congratulations! Now you can see a small circle displayed on your OLED screen!
//!
//! If you want to apply your own configuration for the SSD1315 (for example, to change the contrast),
//! follow this example:
//!
//! ```rust
//! use ssd1315::*;
//! use embedded_graphics::{
//!     pixelcolor::BinaryColor,
//!     prelude::*,
//!     primitives::{Circle, PrimitiveStyle},
//! };
//!
//! let interface = interface::I2cDisplayInterface::new(i2c);
//! // let interface = interface::SpiDisplayInterface::new(spi, dc);
//!
//! let mut config = config::Ssd1315Config::new();
//! config.contrast = 0xff;
//!
//! let mut display = Ssd1315::new(interface);
//!
//! Circle::new(Point::new(0, 0), 40)
//!         .into_styled(PrimitiveStyle::with_fill(BinaryColor::On))
//!         .draw(&mut display)
//!         .unwrap();
//!
//! display.init(config).unwrap();
//! display.flush().unwrap();
//! ```
//!
//! Alternatively, you can use a preset configuration provided by `ssd1315`:
//!
//! ```rust
//! let config = config::Ssd1315Config::preset_config();
//! ```
//!
//! Now you can see the change in contrast!
//!
//! You might also want to draw some raw image(s) manually to fit your specific requirements.
//! That's no problem! You can draw it/them in an easy way:
//!
//! ```rust
//! let mut display = Ssd1315::new(interface);
//!
//! let raw_image = [[0b1010_1010; 128]; 8];
//! *display.buffer_mut() = raw_image;
//!
//! display.init(Default::default()).unwrap();
//! display.flush().unwrap();
//! ```

#![no_std]

pub mod command;
pub mod config;
mod draw_buffer;
pub mod interface;

use crate::command::{Command, Page};
use config::Ssd1315Config;
use display_interface::{DataFormat, DisplayError, WriteOnlyDataCommand};

#[cfg(feature = "async")]
use crate::command::CommandAsync;
#[cfg(feature = "async")]
use display_interface::AsyncWriteOnlyDataCommand;

pub const WIDTH: usize = 128;
pub const HEIGHT: usize = 64;

/// A virtual SSD1315 device that holds interface data, a buffer
/// that maps to the actual buffer in the SSD1315 and a configuration.

#[maybe_async_cfg::maybe(sync(keep_self), async(feature = "async"))]
pub struct Ssd1315<DI> {
    interface: DI,
    buffer: [[u8; WIDTH]; 8],
}

#[maybe_async_cfg::maybe(
    sync(keep_self),
    async(
        feature = "async",
        idents(Command, WriteOnlyDataCommand(async = "AsyncWriteOnlyDataCommand"),)
    )
)]
impl<DI: WriteOnlyDataCommand> Ssd1315<DI> {
    /// Creates a new instance of SSD1315.
    ///
    /// The `interface` can be either an I2C or an SPI interface.
    pub fn new(interface: DI) -> Self {
        Self {
            interface,
            buffer: [[0; WIDTH]; 8],
        }
    }

    /// Initializes the SSD1315.
    /// config - Configuration for the SSD1315.
    pub async fn init(&mut self, config: Ssd1315Config) -> Result<(), DisplayError> {
        let init_commands = [
            // Display off
            Command::DisplayOn(false),
            // Set display clock divide ratio/oscillator frequency
            Command::DisplayClockDiv(
                (config.display_clock_divide_ratio_and_oscillator_freq >> 4) & 0x0F,
                config.display_clock_divide_ratio_and_oscillator_freq & 0x0F,
            ),
            // Set multiplex ratio
            Command::Multiplex(config.multiplex_ratio),
            // Set display offset
            Command::DisplayOffset(config.display_offset),
            // Set display start line
            Command::StartLine(config.start_line),
            // Set segment remap
            Command::SegmentRemap(config.segment_remap),
            // Set COM output scan direction
            Command::ReverseComDir(config.reverse_com),
            // Set COM pins hardware configuration
            Command::ComPinConfig(
                (config.com_pins_hardware_config >> 4) & 0x01 != 0,
                (config.com_pins_hardware_config >> 5) & 0x01 != 0,
            ),
            // Set contrast control
            Command::Contrast(config.contrast),
            // Set pre-charge period
            Command::PreChargePeriod(
                config.precharge_period & 0x0F,
                (config.precharge_period >> 4) & 0x0F,
            ),
            // Set VCOMH deselect level
            Command::VcomhDeselect(config.v_comh_select_level),
            // Entire display ON (resume to RAM content display)
            Command::AllOn(false),
            // Set normal/inverse display
            Command::Invert(config.inverse_display),
            // Set charge pump
            Command::ChargePump(config.charge_pump_level),
            // Display on
            Command::DisplayOn(true),
        ];

        for cmd in init_commands {
            cmd.send(&mut self.interface).await?;
        }
        Ok(())
    }

    /// Flushes the SSD1315 buffer to display its contents on the OLED screen.
    pub async fn flush(&mut self) -> Result<(), DisplayError> {
        let pages = [
            Page::Page0,
            Page::Page1,
            Page::Page2,
            Page::Page3,
            Page::Page4,
            Page::Page5,
            Page::Page6,
            Page::Page7,
        ];

        for (page, data) in pages.iter().zip(self.buffer.iter()) {
            Command::PageStart(*page).send(&mut self.interface).await?;
            Command::LowerColStart(0).send(&mut self.interface).await?;
            Command::UpperColStart(0).send(&mut self.interface).await?;

            self.interface.send_data(DataFormat::U8(data)).await?;
        }

        Ok(())
    }

    /// Clear the internal buffer.
    pub fn clear_buffer(&mut self) {
        self.buffer = [[0; WIDTH]; 8];
    }

    /// Clear the full screen
    pub async fn clear(&mut self) -> Result<(), DisplayError> {
        self.clear_buffer();
        self.flush().await
    }

    /// Release the contained interface.
    pub fn release(self) -> DI {
        self.interface
    }
}

/// Getter methods for the interface and buffer.
#[maybe_async_cfg::maybe(
    sync(keep_self),
    async(
        feature = "async",
        idents(WriteOnlyDataCommand(async = "AsyncWriteOnlyDataCommand"),)
    )
)]
impl<DI: WriteOnlyDataCommand> Ssd1315<DI> {
    /// Get the display interface.
    pub fn interface(&mut self) -> &DI {
        &self.interface
    }

    /// Get the display interface.
    pub fn interface_mut(&mut self) -> &mut DI {
        &mut self.interface
    }

    /// Get a immutable reference to the SSD1315 buffer.
    pub fn buffer(&mut self) -> &[[u8; WIDTH]; 8] {
        &self.buffer
    }

    /// Get a mutable reference to the SSD1315 buffer.
    pub fn buffer_mut(&mut self) -> &mut [[u8; WIDTH]; 8] {
        &mut self.buffer
    }
}

/// Additional methods for controlling the display.
#[maybe_async_cfg::maybe(
    sync(keep_self),
    async(
        feature = "async",
        idents(Command, WriteOnlyDataCommand(async = "AsyncWriteOnlyDataCommand"),)
    )
)]
impl<DI: WriteOnlyDataCommand> Ssd1315<DI> {
    /// Turn the display on or off. The display can be drawn to and retains all
    /// of its memory even while off.
    pub async fn set_display_on(&mut self, on: bool) -> Result<(), DisplayError> {
        Command::DisplayOn(on).send(&mut self.interface).await
    }

    /// Set the screen pixel on/off inversion
    pub async fn set_invert(&mut self, invert: bool) -> Result<(), DisplayError> {
        Command::Invert(invert).send(&mut self.interface).await
    }

    /// Change the display brightness.
    ///
    /// `brightness` should be a value between 0x00 and 0xFF.
    pub async fn set_brightness(&mut self, brightness: u8) -> Result<(), DisplayError> {
        Command::PreChargePeriod(1, brightness)
            .send(&mut self.interface)
            .await?;
        Command::Contrast(brightness)
            .send(&mut self.interface)
            .await
    }

    /// Set the column address in the framebuffer of the display where any sent data should be
    /// drawn.
    pub async fn set_column(&mut self, column: u8) -> Result<(), DisplayError> {
        Command::LowerColStart(column)
            .send(&mut self.interface)
            .await?;
        Command::UpperColStart(column)
            .send(&mut self.interface)
            .await
    }

    /// Set the page address (row 8px high) in the framebuffer of the display where any sent data
    /// should be drawn.
    ///
    /// Note that the parameter is in pixels, but the page will be set to the start of the 8px
    /// row which contains the passed-in row.
    pub async fn set_row(&mut self, row: u8) -> Result<(), DisplayError> {
        Command::PageStart(row.into())
            .send(&mut self.interface)
            .await
    }

    /// Send a raw buffer to the display.
    pub async fn draw(&mut self, buffer: &[u8]) -> Result<(), DisplayError> {
        self.interface.send_data(DataFormat::U8(buffer)).await
    }
}