3.4. Inkplate esp-idf

3.4.1. System Functions

3.4.1.1. Inkplate object initialization

To use any of Inkplates functionalities you need to include Inkplate header, as mentioned on the Index and Get Started pages. After you’ve done that you can create a new instance of the Inkplate object, like this:

Inkplate display(DisplayMode::INKPLATE_1BIT);

or

Inkplate display(DisplayMode::INKPLATE_3BIT);

depending on what you need, monochrome (INKPLATE_1BIT) of grayscale (INKPLATE_3BIT) functionality.

In here given examples, Inkplate object will always be named display, if not said otherwise. After calling this below your “#include” lines, you have access to all Inkplate functionality as display object methods.

3.4.1.2. begin() method

Before calling any display method you must call .begin() like this:
display.begin();
  • Description:

    If you forget to do this most method calls will result in core panick and esp32 resetting. For most use cases this function is called in Arduino’s setup function. After you’ve done this you can proceed calling all other methods described below.

3.4.1.3. Inkplate::einkOff();

  • Method prototype (as seen in inkplate.hpp):

inline void einkOff();
  • Arguments and return value:
    No Arguments.
    Returns nothing.
  • Description:
    Turns the panel off to save energy.
  • Example:
    display.einkOff();
    

3.4.1.4. Inkplate::einkOn();

  • Method prototype (as seen in inkplate.hpp):

void einkOn();
  • Arguments and return value:
    No Arguments.
    Returns nothing.
  • Description:
    Turns the panel back on.
  • Example:
    display.einkOn();
    

3.4.1.5. Inkplate::getPanelState();

  • Method prototype (as seen in inkplate.hpp):

uint8_t getPanelState();
  • Arguments and return value:
    No Arguments.
    Returns 1 if eink panel is on, and 0 if it’s off.
  • Description:
    Used to see if the panel is on.
  • Example:
    Serial.print(display.getPanelState(), DEC);
    

3.4.1.6. Inkplate::readBattery();

  • Method prototype (as seen in inkplate.hpp):

double readBattery();
  • Arguments and return value:
    No Arguments.
    Returns battery voltage as a double.
  • Description:
    Function used to determine battery voltage.
    Can be used to display how much more time will the device be on.
  • Example:
    double voltage = display.readBattery();
    

3.4.1.7. Inkplate::readTemperature();

  • Method prototype (as seen in inkplate.hpp):

int8_t readTemperature();
  • Arguments and return value:
    No arguments.
    Returns panel temperature at the last refresh.
  • Description:
    Can be used to determine temperature roughly.
    Keep in mind that the returned value was measured at the time of the last screen refresh.
  • Example:
    int  temp = display.readTemperature();
    

3.4.1.8. Inkplate::readTouchpad();

  • Method prototype (as seen in inkplate.hpp):

uint8_t readTouchpad(int c);
  • Arguments and return value:
    int c - pass in PAD1, PAD2 or PAD3
    Returns state of the desired pad.
  • Description:
    Reads the state of each of three pads.
  • Example:
    if (display.readTouchpad(PAD1))
    {
        //Do something
    }
    

3.4.1.9. Inkplate::sdCardInit();

  • Method prototype (as seen in inkplate.hpp):

bool sdCardInit();
  • Arguments and return value:
    No Arguments
    Returns 0 if card initialization unsuccessful, else some number which casts to true.
  • Description:
    Used to initialize SD card interface.
    Must be called before using SD card functionality like SdFile::read();

3.4.2. Graphics Functions

3.4.2.1. Inkplate::setRotation();

  • Method prototype (as seen in graphics.hpp):

void setRotation(uint8_t r);
  • Arguments and return value:
    uint8_t r - screen rotation.
    Returns nothing.
  • Description:
    Rotates the screen to be used in different orientations.
    Default is 2, to flip 180 input 4
    1 and 3 are for portait mode.
    Once flipped coordinate space remains to have the origin in the top left corner.
  • Example:
    display.setRotation(3);
    
    display.setCursor(100, 100);
    display.print("INKPLATE");
    
  • Result:
    Here is what the code above produces:
    _images/IMG_4347.jpg

3.4.2.2. Inkplate::getRotation();

  • Method prototype (as seen in graphics.hpp):

uint8_t getRotation(void);
  • Arguments and return value:
    No arguments.
    Returns nothing.
  • Description:
    Returns screen rotation, in range [0,3], 2 is default.
  • Example:
    if(display.getRotation() == 4)
        display.print("I'm upside down!");
        display.display();
    

3.4.2.3. Inkplate::drawPixel();

  • Method prototype (as seen in graphics.hpp):

void drawPixel(int16_t x0, int16_t y0, uint16_t color);
  • Arguments and return value:
    int16_t x0 - x coordinate of pixel, [0, 799] in rotations 2, 4 and [0, 599] in 1, 3
    int16_t y0 - y coordinate of pixel, [0, 599] in rotations 2, 4 and [0, 799] in 1, 3
    uint16_t color - pixel color, in 3 bit mode in range [0, 7]

    Returns nothing.

  • Description:
    Most basic drawing command in the library is .drawPixel();
    Draws one pixel at x0, y0 in desired color.
    Requires Inkplate::display() to be called afterwards to update the screen,
    See below.
  • Example:
    display.drawPixel(100, 50, BLACK);
    
  • Result:
    Here is what the code above produces:
    Quite small, isn’t it.
    _images/IMG_4345.jpg

3.4.2.4. Inkplate::selectDisplayMode();

  • Method prototype (as seen in graphics.hpp):

void selectDisplayMode(DisplayMode mode)
  • Arguments and return value:
    DisplayMode mode mode - New display mode, INKPLATE_1BIT or INKPLATE_3BIT.
    Returns nothing.
  • Description:
    Changes the screen mode to from monochrome to 3 bit grayscale or vice versa.
  • Example:
    display.selectDisplayMode(DisplayMode::INKPLATE_3BIT);
    

3.4.2.5. Inkplate::getDisplayMode();

  • Method prototype (as seen in graphics.hpp):

DisplayMode getDisplayMode();
  • Arguments and return value:
    No arguments.
    Returns currently set display mode.
  • Description:
    Used to determine which display mode is currently used.
    Returns DisplayMode::INKPLATE_1BIT or DisplayMode::INKPLATE_3BIT.
  • Example:
    if(display.getDisplayMode() == DisplayMode::INKPLATE_3BIT)
    {
        display.print("I'm in grayscale mode!");
        display.display()
    }
    

3.4.2.6. Inkplate::clearDisplay();

  • Method prototype (as seen in graphics.hpp):

void clearDisplay();
  • Arguments and return value:
    No Arguments
    Returns nothing.
  • Description:
    Clears all data in buffer. Call display() after this to update/clear display.
  • Example:
    display.clearDisplay();
    display.display();
    

3.4.2.7. Inkplate::display();

  • Method prototype (as seen in graphics.hpp):

void display();
  • Arguments and return value:
    No Arguments
    Returns nothing.
  • Description:
    Displays all data in frame buffer to screen.
  • Example:
    //Any drawing code
    display.drawPixel(10, 100, BLACK);
    
    display.display();
    

3.4.2.8. Inkplate::partialUpdate();

  • Method prototype (as seen in graphics.hpp):

void partialUpdate();
  • Arguments and return value:
    No Arguments
    Returns nothing.
  • Description:
    Updates only the changed parts of the screen. (monochrome/INKPLATE_1BIT mode only!)
    After a few updates creates blurry parts of the screen.
    Fixed by calling Inkplate::clean();
  • Example:
    display.drawPixel(100, 50, BLACK);
    
    display.partialUpdate();
    
    display.drawPixel(100, 100, BLACK);
    

3.4.2.9. Inkplate::width();

  • Method prototype (as seen in graphics.hpp):

int16_t width();
  • Arguments and return value:
    No arguments.
  • Description:
    Returns screen width.
  • Example:
    display.width();
    

3.4.2.10. Inkplate::height();

  • Method prototype (as seen in graphics.hpp):

int16_t height(void);
  • Arguments and return value:
    No arguments.

    Returns nothing.

  • Description:
    Returns screen height.
  • Example:
    display.height();
    

3.4.2.11. Inkplate::drawImage();

  • Method prototype (as seen in Image.h):

bool drawImage(const char *path, int x, int y, bool dither = 1, bool invert = 0);
bool drawImage(const String path, int x, int y, bool dither = 1, bool invert = 0);
bool drawImage(const uint8_t *buf, int x, int y, int16_t w, int16_t h, uint8_t c = BLACK, uint8_t bg = 0xFF);
bool drawImage(const char *path, const Format &format, const int x, const int y, const bool dither = 1, const bool invert = 0);
bool drawImage(const String path, const Format &format, const int x, const int y, const bool dither = 1, const bool invert = 0);
bool drawImage(const char *path, const Format &format, const Position &position, const bool dither = 1, const bool invert = 0);
  • Arguments and return value:
    const char *path - Path to file.
    int x - x coordinate to draw the image at
    int y - y coordinate to draw the image at
    bool dither - to dither the image or not
    bool invert - invert all colors, defaults to false

    const String path - Path to file.
    int x - x coordinate to draw the image at
    int y - y coordinate to draw the image at
    bool dither - to dither the image or not
    bool invert - invert all colors, defaults to false

    const uint8_t *p - Buffer to draw from.
    int x - x coordinate to draw the image at
    int y - y coordinate to draw the image at
    int16_t w - x coordinate to draw the image at
    int16_t h - y coordinate to draw the image at
    bool dither - to dither the image or not
    bool invert - invert all colors, defaults to false
    uint8_t c - color to draw 1 pixels if in BW mode
    uint8_t bg - color to draw all 0 pixels if in BW mode.
    const char *path - Path to file.
    const Format &format - image format (bmp, jpeg, png).
    int x - x coordinate to draw the image at
    int y - y coordinate to draw the image at
    bool dither - to dither the image or not
    bool invert - invert all colors, defaults to false
    const String *path - Path to file.
    const Format &format - image format (bmp, jpeg, png).
    int x - x coordinate to draw the image at
    int y - y coordinate to draw the image at
    bool dither - to dither the image or not
    bool invert - invert all colors, defaults to false
    const char *path - Path to file.
    const Format &format - image format (bmp, jpeg, png).
    const Position &position - image position (Center, TopLeft, BottomLeft, TopRight, BottomRight, _npos)
    bool dither - to dither the image or not
    bool invert - invert all colors, defaults to false

    Returns 0 if error occured, else returns 1.

  • Description:
    Should always have Inkplate::sdCardInit() called before if file is from SD.
    Can draw all kinds of images, but they should have a file extensions in them.
    Can draw from web if path starts with http:// or https:// or if not from SD.
    Draws bmp, png and jpeg images.
    Automatically adjusts for current display mode.

3.4.3. Shapes Functions

3.4.3.1. Inkplate::drawElipse();

  • Method prototype (as seen in shapes.hpp):

void drawElipse(int rx, int ry, int xc, int yc, int c);
  • Arguments and return value:
    int rx - Elipse X radius.
    int ry - Elipse Y radius.
    int xc - Elipse center x.
    int yc - Elipse center y.
    int color - Elipse color (just the edge, see fillElipse for fully filled).

    Returns nothing.

  • Description:
    Draws an empty(not filled) elipse.
  • Example:
    display.drawElipse(100, 200, 400, 300, 0);
    

3.4.3.2. Inkplate::fillElipse();

  • Method prototype (as seen in shapes.hpp):

void fillElipse(int rx, int ry, int xc, int yc, int c);
  • Arguments and return value:
    int rx - Elipse X radius.
    int ry - Elipse Y radius.
    int xc - Elipse center x.
    int yc - Elipse center y.
    int color - Elipse color.

    Returns nothing.

  • Description:
    Draws an filled elipse.
  • Example:
    display.fillElipse(100, 200, 400, 300, 0);
    

3.4.3.3. Inkplate::drawPolygon();

  • Method prototype (as seen in shapes.hpp):

void drawPolygon(int *x, int *y, int n, int color);
  • Arguments and return value:
    int *x - Polygon points X coordinates.
    int *y - Polygon points Y coordinates.
    int n - Number of points.
    int color - Elipse color (just the edge, see fillElipse for fully filled).

    Returns nothing.

  • Description:
    Draws an empty(not filled) polygon.
  • Example:
    display.drawPolygon(xt, yt, n, 0);
    

3.4.3.4. Inkplate::fillPolygon();

  • Method prototype (as seen in shapes.hpp):

void fillPolygon(int *x, int *y, int n, int color);
  • Arguments and return value:
    int *x - Polygon points X coordinates.
    int *y - Polygon points Y coordinates.
    int n - Number of points.
    int color - Elipse color (just the edge, see fillElipse for fully filled).

    Returns nothing.

  • Description:
    Draws a filled polygon.
    Can be quite slow.
  • Example:
    display.fillPolygon(xt, yt, n, 0);
    

3.4.3.5. Inkplate::drawThickLine();

  • Method prototype (as seen in shapes.hpp):

void drawThickLine(int x1, int y1, int x2, int y2, int color, float thickness);
  • Arguments and return value:
    int x1 - x coordinate of line start, [0, 799] in rotations 2, 4 and [0, 599] in 1, 3
    int y1 - y coordinate of line start, [0, 599] in rotations 2, 4 and [0, 799] in 1, 3
    int x2 - x coordinate of line end, [0, 799] in rotations 2, 4 and [0, 599] in 1, 3
    int y2 - y coordinate of line end, [0, 599] in rotations 2, 4 and [0, 799] in 1, 3
    int color - line color, in 3 bit mode in range [0, 7]
    float thickness - line thickness in pixels

    Returns nothing.

  • Description:
    For drawing thick lines.
  • Example:
    display.drawThickLine(random(0, 799), random(0, 599), random(0, 799), random(0, 599), BLACK, (float)random(1, 20));
    
  • Result:
    Here is what the code above produces:
    _images/IMG_4350.jpg

3.4.3.6. Inkplate::drawGradientLine();

  • Method prototype (as seen in shapes.hpp):

void drawGradientLine(int x1, int y1, int x2, int y2, int color1, int color2, float thickness = -1);
  • Arguments and return value:
    int x1 - x coordinate of line start, [0, 799] in rotations 2, 4 and [0, 599] in 1, 3
    int y1 - y coordinate of line start, [0, 599] in rotations 2, 4 and [0, 799] in 1, 3
    int x2 - x coordinate of line end, [0, 799] in rotations 2, 4 and [0, 599] in 1, 3
    int y2 - y coordinate of line end, [0, 599] in rotations 2, 4 and [0, 799] in 1, 3
    int color1 - start line color, in 3 bit mode in range [0, 7]
    int color2 - start line color, in 3 bit mode in range [0, 7]
    float thickness - line thickness, defaults to -1 meaning use normal, non thick, line.

    Returns nothing.

  • Description:
    For drawing color gradient lines.
    color1 should always be less than color2.
  • Example:
    int startColor = random(0, 7);
    int endColor = random(startColor, 7);
    display.drawGradientLine(random(0, 799), random(0, 599), random(0, 799), random(0, 599), startColor, endColor, (float)random(1, 20));
    
  • Result:
    Here is what the code above produces:
    _images/IMG_4353.jpg

3.4.4. Network Client

3.4.4.1. Inkplate::disconnect();

  • Method prototype (as seen in inkplate.hpp):

void disconnect();
  • Arguments and return value:
    No arguments.
    Returns nothing.
  • Description:
    Disconnects Inkplate from wifi network (shuts network).
  • Example:
    display.disconnect();
    

3.4.4.2. Inkplate::isConnected();

  • Method prototype (as seen in inkplate.hpp):

bool isConnected();
  • Arguments and return value:
    No arguments.
    Returns 1 if connected to wifi, 0 if not.
  • Description:
    Checks if inkplate is connected to wifi.
  • Example:
    if(display.isConnected())
    {
        //Do something
    }
    

3.4.4.3. Inkplate::joinAP();

  • Method prototype (as seen in inkplate.hpp):

bool joinAP(const char *ssid, const char *pass);
  • Arguments and return value:
    const char *ssid - name of the wifi network.
    const xhar *pass - network password.
    Returns 1 if successfuly connected, 0 if not.
  • Description:
    Sets and connects inkplate to wifi network.
  • Example:
    //In setup
    while(!display.joinAP(ssid, pass))
    {
        Serial.println("Connecting to wifi");
    }
    

3.4.4.4. Inkplate::downloadFile();

  • Method prototype (as seen in network_client.hpp):

uint8_t *downloadFile(const char *url, int32_t *defaultLen);
  • Arguments and return value:
    const char *url - link to file.
    int32_t *defaultLen - expected lenght (only matters if real length cant be checked).
    Returns file as byte buffer, NULL if failed to get file.
  • Description:
    Downloads file from given url.
  • Example:
    char url = "https//:www.somepic.com/pic.jpg"
    int32_t len = 54373;
    jpeg file = display.downloadFile(url, len);
    

3.4.5. ESP Functions

3.4.5.1. Inkplate::millis();

  • Method prototype (as seen in esp.hpp):

long millis();
  • Arguments and return value:
    No arguments.
    Returns time in milliseconds since boot.
  • Description:
    Returns time in milliseconds since boot.
  • Example:
    long time = millis();
    

3.4.5.2. Inkplate::delay_microseconds();

  • Method prototype (as seen in esp.hpp):

void delay_microseconds(uint32_t micro_seconds);
  • Arguments and return value:
    uint32_t micro_seconds.
    Returns nothing.
  • Description:
    Stops program for given micro_seconds.
  • Example:
    delay_microseconds(2000000)//waits for 2 seconds
    

3.4.5.3. Inkplate::delay();

  • Method prototype (as seen in esp.hpp):

void delay(uint32_t milliseconds);
  • Arguments and return value:
    uint32_t milliseconds.
    Returns nothing.
  • Description:
    Stops program for given milliseconds.
  • Example:
    delay(2000)//waits for 2 seconds
    

3.4.5.4. Inkplate::analog_read();

  • Method prototype (as seen in esp.hpp):

int16_t analog_read(adc1_channel_t channel);
  • Arguments and return value:
    adc1_channel_t channel to read from.
    Returns read value.
  • Description:
    Returns read value from channel/pin.
  • Example:
    float val = analog_read(15);
    

3.4.6. Wire Functions

3.4.6.1. Inkplate::begin_transmission();

  • Method prototype (as seen in wire.hpp):

void begin_transmission(uint8_t addr);
  • Arguments and return value:
    uint8_t addr device address we will establish communication with.
    Returns nothing.
  • Description:
    Starts communication with device.
  • Example:
    begin_transmission(0xH3);
    

3.4.6.2. Inkplate::end_transmission();

  • Method prototype (as seen in wire.hpp):

void end_transmission();
  • Arguments and return value:
    No Arguments.
    Returns nothing.
  • Description:
    Ends communication with device.
  • Example:
    end_transmission();
    

3.4.6.3. Inkplate::write();

  • Method prototype (as seen in wire.hpp):

void write(uint8_t val);
  • Arguments and return value:
    uint8_t val data that will be sent to device.
    Returns nothing.
  • Description:
    Sends data to device.
  • Example:
    uint8_t data = 0x21;
    write(data);
    

3.4.6.4. Inkplate::read();

  • Method prototype (as seen in wire.hpp):

void read(uint8_t val);
  • Arguments and return value:
    No Arguments.
    Returns data from device.
  • Description:
    Reads data from device.
  • Example:
    uint8_t data = read();
    

3.4.6.5. Inkplate::request_from();

  • Method prototype (as seen in wire.hpp):

esp_err_t request_from(uint8_t addr, uint8_t size);
  • Arguments and return value:
    uint8_t addr device address to request data from.
    uint8_t size number of bytes we are requesting.
    Returns esp_err_t value that indicates successful or failed connection.
  • Description:
    Requests data from device.
  • Example:
    esp_err_t error = request_from(0xH3, 7);
    

3.4.7. MCP Functions

3.4.7.1. Inkplate::set_direction();

  • Method prototype (as seen in mcp.hpp):

void set_direction(Pin pin, PinMode mode);
  • Arguments and return value:
    Pin pin pin number.
    PinMode mode pin mode.
    Returns nothing.
  • Description:
    Sets device pin mode (INPUT, INPUT_PULLUP OUTPUT).
  • Example:
    display.set_direction(11, OUTPUT);
    

3.4.7.2. Inkplate::digital_write();

  • Method prototype (as seen in mcp.hpp):

void digital_write(Pin pin, SignalLevel state);
  • Arguments and return value:
    Pin pin pin number.
    SignalLevel state HIGH or LOW signal.
    Returns nothing.
  • Description:
    Sets device output state (HIGH or LOW).
  • Example:
    display.digital_write(11, SignalLevel::HIGH);
    

3.4.7.3. Inkplate::digital_read();

  • Method prototype (as seen in mcp.hpp):

SignalLevel digital_read(Pin pin);
  • Arguments and return value:
    Pin pin pin number.
    Returns pin INPUT state (HIGH or LOW).
  • Description:
    Gets pin input state (HIGH or LOW).
  • Example:
    uint8_t pin_state = display.digital_read(11);
    

3.4.7.4. Inkplate::set_int_output();

  • Method prototype (as seen in mcp.hpp):

void set_int_output(IntPort intPort, bool mirroring, bool openDrain, SignalLevel polarity);
  • Arguments and return value:
    IntPort intPort - intPort portA or portB.
    bool mirroring - mirroring set 1 to make ports mirror each other so that any interrupt will cause both to go HIGH.
    bool openDrain - openDrain set 1 to set interupt port as open drain, this will override port polarity.
    SignalLevel polarity - sets port interrupt polarity, 1 active high, 0 active low.
    Returns nothing.
  • Description:
    Sets port interupt state.
  • Example:
    display.set_int_output(IntPort::INTPORTA, 0, 0, SignalLevel::LOW);
    

3.4.7.5. Inkplate::set_int_pin();

  • Method prototype (as seen in mcp.hpp):

void set_int_pin(Pin pin, IntMode mode);
  • Arguments and return value:
    Pin pin - pin number.
    IntMode mode - interrupt mode (CHANGE, FALLING, RISING).
    Returns nothing.
  • Description:
    Sets pin interupt state.
  • Example:
    display.set_int_pin(11,IntMode::CHANGE);
    

3.4.7.6. Inkplate::remove_int_pin();

  • Method prototype (as seen in mcp.hpp):

void remove_int_pin(Pin pin);
  • Arguments and return value:
    Pin pin - pin number.
    Returns nothing.
  • Description:
    Removes interupt from pin.
  • Example:
    display.remove_int_pin(11);
    

3.4.7.7. Inkplate::get_int();

  • Method prototype (as seen in mcp.hpp):

void get_int();
  • Arguments and return value:
    No Arguments.
    Returns interupt registers state.
  • Description:
    Returns interrupt registers state for portA and portB.
    Every bit represents interrupt pin, MSB is PORTB PIN7, LSB is PORTA PIN1.
  • Example:
    display.get_int();
    

3.4.7.8. Inkplate::get_int_state();

  • Method prototype (as seen in Mcp.h):

uint16_t get_int_state();
  • Arguments and return value:
    No argument.
    Returns interupt registers state at the time interrupt occured.
  • Description:
    Returns interrupt registers state for portA and portB.
    Every bit represents interrupt pin, MSB is PORTB PIN7, LSB is PORTA PIN1.
  • Example:
    uint16_t intrrupts = display.get_int_state();
    

3.4.7.9. Inkplate::set_ports();

  • Method prototype (as seen in Mcp.h):

void set_ports(uint16_t values);
  • Arguments and return value:
    uint16_t values - values to be writen to port A and port B registers.
    Returns nothing.
  • Description:
    sets internal state of PORTA and PORTB registers.
    MSB byte is for PORTB, LSB byte for PORTA
  • Example:
    uint16_t data = 0xFFFF;//to make all bits ones
    display.set_ports(data);
    

3.4.7.10. Inkplate::getPorts();

  • Method prototype (as seen in Mcp.h):

uint16_t getPorts();
  • Arguments and return value:
    No arguments.
    Returns register states of PORTA and PORTB.
  • Description:
    returns internal states of PORTA and PORTB registers.
    MSB byte is for PORTB, LSB is for PORTA.
  • Example:
    display.getPorts();