M5GFXライブラリの始め方

このドキュメントはArduino IDE用のライブラリであるM5GFXの始め方を簡単に紹介します。

M5GFXとは

M5GFXは、M5Stack製品の仕様の異なるディスプレイデバイスを扱うためのライブラリです。LCD,OLED,e-Ink Display等の違いを意識せず共通のAPIで扱うことが可能です。(初期化処理等で一部異なるAPIも存在します。)

ESP-IDFでも利用可能

Arduinoフレームワークだけでなく、ESP-IDFでも利用可能です。

M5GFXの対応機種及び周辺機器

使用可能なメモリにも依存しますが、メインデバイス+UnitLCDやメインデバイス+UnitOLEDという組み合わせも可能です。

メインデバイス

  • M5Stack Core Basic/Gray/Fire/M5Go

  • M5Stack Core2/Core2 for AWSIoT Edukit

  • M5StickC/M5StickCPlus

  • M5Tough

  • M5Paper

  • M5CoreInk

  • M5Station

Unit

  • UnitLCD

  • UnitOLED

AtomDisplay

  • AtomDisplay/AtomDisplayLite

ライブラリのインストール

Arduino IDE

メニュー→「スケッチ」→「ライブラリをインクルード」→「ライブラリを管理」をクリックして、ライブラリマネージャを開き、M5GFXというライブラリを検索しインストールします。

使い方

ライブラリのInclude

注意: 使用するデバイスによりIncludeするヘッダファイルが異なります。

メインデバイス

UnitLCD

UnitOLED

M5AtomDisplay

組み合わせる場合 メインデバイスとUnitLCDやUnitOLEDを組み合わせる場合は複数Includeします。

例、

#include <M5GFX.h>
#include <M5UnitOLED.h>

M5GFX gfx;
M5UnitOLED oled;

M5Stackのライブラリと組み合わせる

  • 下記のライブラリではM5.Display(またはM5.Lcd)でM5GFXが利用できます。(M5GFX.hのincludeは不要)

    #include <M5Unified.h>
    
    void setup() {
        auto cfg = M5.config();
        M5.begin(cfg);
    
        M5.Display.init();
        M5.Display.startWrite();
        M5.Display.println("Hello World!");
        M5.Display.endWrite();
    }
    
    void loop() {
    }
    
  • 下記のライブラリではM5GFXをIncludeして、定義が必要です。
    M5.Lcd(またはM5.Display)を使ってしまうとそれぞれのライブラリに含まれたディスプレイドライバを利用するので注意してください。

    #include <M5Stack.h>
    #include <M5GFX.h>
    
    static M5GFX gfx;
    
    void setup() {
        M5.begin();
        gfx.begin();
        gfx.startWrite();
        gfx.println("Hello World!");
        gfx.endWrite();
    }
    void loop() {
    }
    

描画関数を実行するときはstartWrite(),endWrite()で囲う。

線を1本描く(drawLine)や文字表示(drawString)を1行行うといった単独で描画する場合は内部で実行されているため、速度は変わりませんが、複数の描画処理を行う場合は最初にstartWrite(), 描画を実行した後にendWrite()を実行すると描画が高速になります。

startWrite(),endWrite()の詳しい説明は、 補足説明 を参照してください。

**notice:**startWrite()を実行し、endWrite()を実行するまでの間はSPIバスをパネルアクセスのために専有します。そのためSDカードのアクセスを実行する場合はendWrite()実行後に行わないと、クラッシュしたり、フリーズし予期せぬ動きをします。特に並列処理を行う場合は排他処理を実装してください。

e-Ink displayの描画品質設定(M5Paperのみ)

M5Paperのe-Ink displayは描画品質を指定可能です。

  • epd_mode_t::epd_fastest
    最速モード、描画時に白黒反転は起きない。残像が最も残りやすい。

  • epd_mode_t::epd_fast
    高速モード、描画時に白黒反転は起きない。残像が残りやすい。

  • epd_mode_t::epd_text
    高品質モード、白黒反転が一瞬起きる。白背景で文字を表示するのに適している。

  • epd_mode_t::epd_quality
    高品質モード、白黒反転が一瞬起きる。

M5GFXで扱う色の形式について

カラーコード

M5GFXでは、RGB888形式(24bit)を扱えるようになっています。RGB565形式(16bit)やRGB332形式(8bit)と色の形式を区別するために変数の型を利用しています。カラーコードの対応は下記のようになります。

  • uint32_t
    RGB888形式(24bit)
  • uint16_t(int)
    RGB565形式(16bit)
  • uint8_t
    RGB332形式(8bit)

注意点: 既存のソースをM5GFXに移植した際にカラーコードの変数の型指定を間違えると異なった色が表示されるので注意してください。
例えば、下記のようにRGB565形式の0xFFFF(黒)をunit32_tの変数へ代入した場合、RGB888形式の水色になってしまいます。

#include <Arduino.h>
#include <M5GFX.h>

M5GFX gfx;

void setup()
{
  gfx.begin();
  uint32_t color888 = 0xFFFF;
  uint16_t color565 = 0xFFFF;
  gfx.setTextSize(3);

  gfx.startWrite();
  gfx.setTextColor(color888);
  gfx.println("Color888");
  gfx.setTextColor(color565);
  gfx.println("Color565");
  gfx.endWrite();
}

void loop() {
}

OLED, e-Ink displayの色表現について

OLEDとe-Ink displayの表示は単色です。色を指定した場合は濃淡及び塗りつぶしのパターンが変化します。

M5GFXでHelloWorld

M5Unifiedと組み合わせる

M5.Display(またはM5.Lcd)でM5GFXが利用できます。(Includeは不要)

#include <M5Unified.h>

void setup() {
    auto cfg = M5.config();
    M5.begin(cfg);

    M5.Display.init();

    M5.Display.startWrite();
    M5.Display.println("Hello World!");
    M5.Display.endWrite();
}

void loop() {
}

M5Stack各メインデバイスと組み合わせる

M5.Display(またはM5.Lcd)を使ってしまうとそれぞれのライブラリに含まれたディスプレイドライバを利用するので注意してください。

  • M5Stack

    #include <M5Stack.h>
    #include <M5GFX.h>
    
    static M5GFX gfx;
    
    void setup() {
        M5.begin();
        gfx.begin();
    
        gfx.startWrite();
        gfx.println("Hello World!");
        gfx.endWrite();
    }
    
    void loop() {
    }
    
  • M5Core2

    #include <M5Core2.h>
    #include <M5GFX.h>
    
    static M5GFX gfx;
    
    void setup() {
        M5.begin();
        gfx.init();
    
        gfx.startWrite();
        gfx.println("Hello World!");
        gfx.endWrite();
    }
    
    void loop() {
    }
    
  • M5StickC

    #include <M5StickC.h>
    #include <M5GFX.h>
    
    static M5GFX gfx;
    
    void setup() {
        M5.begin();
        gfx.init();
    
        gfx.startWrite();
        gfx.println("Hello World!");
        gfx.startWrite();
    }
    
    void loop() {
    }
    
  • M5StickC-Plus

    #include <M5StickCPlus.h>
    #include <M5GFX.h>
    
    static M5GFX gfx;
    
    void setup() {
        M5.begin();
        gfx.begin();
    
        gfx.startWrite();
        gfx.println("Hello World!");
        gfx.startWrite();
    }
    
    void loop() {
    }
    
  • M5Tough

    #include <M5Tough.h>
    #include <M5GFX.h>
    
    static M5GFX gfx;
    
    void setup() {
        M5.begin();
        gfx.begin();
    
        gfx.startWrite();
        gfx.println("Hello World!");
        gfx.endWrite();
    }
    
    void loop() {
    }
    
  • M5EPD

    #include <M5EPD.h>
    #include <M5GFX.h>
    
    M5GFX gfx;
    
    void setup()
    {
        gfx.init();
        gfx.setEpdMode(epd_fast);
        gfx.setTextSize(5);
    
        gfx.startWrite();
        gfx.println("Hello World!");
        gfx.endWrite();
    }
    
    void loop() {
    }
    
  • M5Core-Ink

    #include <M5CoreInk.h>
    #include <M5GFX.h>
    
    static M5GFX gfx;
    
    void setup() {
        M5.begin();
        gfx.begin();
    
        gfx.startWrite();
        gfx.println("Hello World!");
        gfx.endWrite();
    }
    
    void loop() {
    }
    
  • M5Station

    #include <M5Station.h>
    #include <M5GFX.h>
    
    static M5GFX gfx;
    
    void setup() {
        M5.begin();
        gfx.begin();
    
        gfx.startWrite();
        gfx.println("Hello World!");
        gfx.endWrite();
    }
    
    void loop() {
    }
    

M5UnitLCD

#include <M5UnitLCD.h>

M5UnitLCD gfx;

void setup(void)
{
  gfx.init();
  gfx.setRotation(1);

  gfx.startWrite();
  gfx.println("Hello World!");
  gfx.endWrite();
}


void loop() {
}

M5UnitOLED

#include <M5UnitOLED.h>

M5UnitOLED gfx;

void setup()
{
  gfx.init();
  gfx.setRotation(1);

  gfx.startWrite();
  gfx.println("Hello World!");
  gfx.endWrite();
}

void loop() {
}

M5AtomDisplay

#include <M5AtomDisplay.h>

M5AtomDisplay gfx(1280, 720);

void setup()
{
  gfx.init();
  gfx.setRotation(1);

  gfx.startWrite();
  gfx.println("Hello World!");
  gfx.endWrite();
}

void loop() {
}

M5GFXとUnitLCDを組み合わせた場合

#include <M5GFX.h>
#include <M5UnitLCD.h>

M5GFX gfx1;
M5UnitLCD gfx2;

void setup() {
    gfx1.init();
    gfx2.init();

    gfx1.startWrite();
    gfx1.println("Hello World! MainDisplay");
    gfx1.endWrite();

    gfx2.startWrite();
    gfx2.println("Hello World! UnitLCD");
    gfx2.endWrite();
}

void loop() {
}

M5GFXとUnitOLEDを組み合わせた場合

#include <M5GFX.h>
#include <M5UnitOLED.h>

M5GFX gfx1;
M5UnitOLED gfx2;

void setup(void) {
    gfx1.init();
    gfx2.init();

    gfx1.startWrite();
    gfx1.println("Hello World! MainDisplay");
    gfx1.endWrite();

    gfx2.startWrite();
    gfx2.println("Hello World! UnitOLED");
    gfx2.endWrite();
}

void loop() {
}

関連ドキュメント

On This Page