M5Stack MicroPython API調査記録 LCD編

※ [M5Cloud README.md](https://github.com/m5stack/M5Cloud/blob/master/README.md)などからのM5Stack MicroPython 固有のAPI調査記録LCD編(2018年1月28日現在)

# **LCD**

LCDを使うには ```m5stack``` モジュールの ```lcd``` オブジェクトをインポートする。

インポート例１:

```python3
from m5stack import lcd
lcd.print('hello world!')
```

インポート例２:

```python3
import m5stack
m5stack.lcd.print('hello world!')
```

インポート例３:

```python3
import m5stack
lcd = m5stack.lcd
lcd.print('hello world!')
```

```lcd``` オブジェクトは実際には ```display``` モジュールにある TFT クラスのインスタンス。このTFTクラスは、M5Stackに取り付けられている**ILI9341**タイプのTFTをSPIで制御する。

----
### ESPとLCDの配線

| ESP32ピン | LCD(ILI9342) | 役割 |
| :-: | :-: | :-- |
| GPIO23 | MOSI | SPI シリアル入力 |
| GPIO18 | SCLK | SPI シリアルクロック |
| GPIO14 | CS  | SPI CS 入力 |
| GPIO27 | DC  | DC (data/command) 入力 |
| GPIO33 | RST  | リセット入力 |


---
#### 色の指定

LCDでの色指定は、24bitの整数値であり、R/G/Bにそれぞれ8ビットを使う(が、有効なのはR/Bで上位5ビット、Gで上位6ビット)。

例： **0xFF0000** は赤、 **0x00FF00** は緑を表す。

lcdオブジェクトには、以下のよく使う色の定義が用意されている。

**BLACK, NAVY, DARKGREEN, DARKCYAN, MAROON, PURPLE, OLIVE, LIGHTGREY, DARKGREY, BLUE, GREEN, CYAN, RED, MAGENTA, YELLOW, WHITE, ORANGE, GREENYELLOW, PINK**

LCDに緑で ```hello world`` を印字するには次のようにする。

```python3
lcd.print('hello world', color=lcd.GREEN)
```

以下のように直接整数値での指定もできる。

```python3
lcd.print('hello world', color=0X00FF00)
```

#### 表示枠

座標指定および描画は表示枠に対して相対的である。初期状態で表示枠は画面全体になるよう設定されている。

#### フォント

利用できる組込みフォントには以下がある。

**FONT_Default, FONT_DefaultSmall, FONT_DejaVu18, FONT_Dejavu24, FONT_Ubuntu, FONT_Comic, FONT_Minya, FONT_Tooney, FONT_Small, FONT_7seg**

---
## LCDのメソッド

### lcd.setBrightness(brightness)

LCDの明るさを *brightness* に設定する(0-255)。

### lcd.setColor(color [,bcolor])

デフォルトの前景色を *color*、背景色を *bgcolor* に設定します。

### lcd.pixel(x, y [,color])

指定座標（x、y）にピクセルを描画する。パラメータ *color* が設定されていない場合は前景色をデフォルトで使う。

### ~~lcd.readPixel(x, y)~~

~~指定座標(x, y)の色の値を取得する。~~

~~現状はなぜか常に 0xffffff が返る。~~

※ LCDがMISOピン結線されていないので使えないそうだ。v0.3.0で削除された。

### lcd.line(x, y, x1, y1 [,color])

座標（x、y）から（x1、y1）まで直線を描きます。パラメータ *color* が指定されていない場合は前景色をデフォルトで使う。

### lcd.lineByAngle(x, y, start, length, angle [,color])

座標(x,y)から *start* 離れたところを始点として長さ *length* の直線を描画する。パラメータ *color* が指定されていない場合は前景色をデフォルトで使う。

パラメータ *angle* には角度(0~359)を与える。

### lcd.triangle(x, y, x1, y1, x2, y2 [,color, fillcolor])

座標(x,y), (x1,y1), (x2,y2)を頂点とした三角形を描画する。パラメータ *color* が指定されていない場合は前景色をデフォルトで使う。

オプションのパラメータ *fillcolor* は三角形を塗りつぶす色を指定する。

### lcd.circle(x, y, r [,color, fillcolor])

座標(x,y)を中心、半径を *r* とした円を描画する。パラメータ *color* が指定されていない場合は前景色をデフォルトで使う。

オプションのパラメータ *fillcolor* は円を塗りつぶす色を指定する。

### lcd.ellipse(x, y, rx, ry [,opt, color, fillcolor])

座標（x、y）と（rx、ry）を2つの焦点として楕円を描画する。パラメータ *color* が指定されていない場合は前景色をデフォルトで使う。

オプションの *opt* は描画部分を指定する。デフォルトは 15 で全体を描画する。以下の描画部分を指定でき、これらの論理和で複数の描画部分も指定できる。
* 1 - 右上部分
* 2 - 左上部分
* 4 - 左下部分
* 8 - 右下部分

オプションのパラメータ *fillcolor* は楕円を塗りつぶす色を指定する。

### lcd.arc(x, y, r, thick, start, end [color, fillcolor])

座標（x、y）を中心とした半径 *r*、開始角度 *start*、終了角度 *end* の円弧を描画する。

円弧のエッジの太さはパラメータ *thick*　で措定する。

パラメータ *color* が指定されていない場合は前景色をデフォルトで使う。

オプションのパラメータ *fillcolor* は円弧のエッジを塗りつぶす色を指定する。

### lcd.polygon(x, y, r, sides, thick [,color, fillcolor, rotate])

座標（x、y）を中心とした半径 *r* の多角形を描画する。パラメータ *sides*　は多角形の辺の数、*thick* はエッジの太さを指定する。

パラメータ *color* が指定されていない場合は前景色をデフォルトで使う。

オプションのパラメータ *fillcolor* は円弧の多角形を塗りつぶす色を指定し、*rotate*　は多角形の回転角度を指定する。

### lcd.rect(x, y, width, height, [color, fillcolor])

座標(x,y)を左上隅の開始位置として、幅 *width* 、高さ *height* の短形を描画する。

パラメータ *color* が指定されていない場合は前景色をデフォルトで使う。

オプションのパラメータ *fillcolor* は短形を塗りつぶす色を指定する。

例:

```python3
lcd.rect(10, 100, 100, 200, 0xFF0000) # 塗りつぶさない
lcd.rect(10, 100, 100, 200, 0xFF0000, 0x00FF00) # 緑で塗りつぶす
```

### lcd.roundrect(x, y, width, height, r [color, fillcolor])

座標(x,y)を左上隅の開始位置として、幅 *width* 、高さ *height* の角を丸めた短形を描画する。パラメータ *r* は丸める角の半径を指定する。

パラメータ *color* が指定されていない場合は前景色をデフォルトで使う。

オプションのパラメータ *fillcolor* は短形を塗りつぶす色を指定する。

### lcd.clear([color]) 

デフォルトの背景色または指定された色 *color* で画面をクリアする。

### lcd.clearWin([color])

デフォルトの背景色または指定された色 *color* で表示枠内をクリアする。

### lcd.orient(orient)

画面の表示方向を設定する。以下の定数が予め定義されている: **tft.PORTRAIT**, **tft.LANDSCAPE**, **tft.PORTRAIT_FLIP**, **tft.LANDSCAPE_FLIP**

### lcd.font(font [,rotate, transparent, fixedwidth, dist, width, outline, color])

フォントを指定します。

Set the active font and its characteristics.

| パラメータ | 説明 |
| :-- | :-- |
| font | フォント名定数またはフォントファイル名を指定 |
| rotate | フォントの回転角度(0~360) |
| transparent | フォントの前景だけ描画するかを指定 |
| fixedwidth | フォントの最大文字幅を固定幅としてフォントを描画する |
| dist | 7-seg フォントのみ、バー間の距離 |
| width | 7-seg フォントのみ、バーの幅 |
| outline | 7-seg フォントのみ、アウトラインの色 |
| color | 塗りつぶし色、指定されていない場合は前景色をデフォルトで使う |

```python3
lcd.font(lcd.FONT_Dejavu24) # フォント FONT_Dejavu24 に設定
```

### lcd.attrib7seg(dist, width, outline, color)

7-セグメントフォントの特徴を設定。

| パラメータ | 説明 |
| :-- | :-- |
| dist | バー間の距離 |
| width | バーの幅 |
| outline | アウトライン色 |
| color | 塗りつぶし色 |


### lcd.fontSize()

現在のフォントの幅と高さをタプルで返す。

### lcd.text(x, y, text [, color])

文字列 *text* を描画する。パラメータ *(x, y)* で印字位置、 *color* で文字色を指定する。

* **x**: 印字する水平位置を指定する。以下の特殊な指定もある:
  * LASTX, 前の印字に張り付くように水平位置を決める
  * CENTER, LCD中央に印字するよう水平位置を決める
  * RIGHT, 右寄せになるよう水平位置を決める

* **y**: 印字する垂直位置を指定する。以下の特殊な指定もある:
  * LASTY, 前の印字に張り付くように垂直位置を決める
  * CENTER, LCD中央に印字するよう垂直位置を決める
  * BOTTOM, 下寄せになるよう垂直位置を決める

* **text**: 表示する文字列。文字列中には以下の２つの特殊文字を指定できる:
  * ‘\r’ CR (0x0D), 行末までクリア
  * ‘\n’ LF (ox0A), 改行

* **color**: 描画する色を指定する。指定されていない場合は前景色をデフォルトで使う。

### lcd.print(text [, x, y, color])

以下を除いて *lcd.text()* と同じ。

* 表示する文字列 *text* が第１パラメータ
* x, yの指定がオプションパラメータで、それぞれ *LASTX, LASTY* を指定したことになる

### lcd.println(text, [x, y, color])

最後に改行する以外は *lcd.print()* と同じ。

例：

```python3
from m5stack import lcd

# hello world を表示
lcd.print('hello world')

# 座標 x=10,y=100 に hello world を表示
lcd.print('hello world', 10, 100)

# 緑色で hello world を表示
lcd.print('hello wrold', color=0x00FF00)

# 座標 x=10,y=100　に赤色で hello world を表示
lcd.print('hello world', 10, 200, 0xFF0000) 

# フォント FONT_Dejavu24 に設定
lcd.font(lcd.FONT_Dejavu24)
lcd.println('hello world')  # 表示の後に改行
```

### lcd.textWidth(text)

文字列 *text* のフォント占有幅を返す。

### lcd.textClear(x, y, text [, color])

座標 *(x,y)* に文字列 *text*　によって使われる領域を、デフォルトの背景色または指定された色 *color* で画面をクリアする。

### lcd.image(x, y, file [,scale, type])

座標 *(x,y)* を開始位置として画像ファイル *file* を表示します。

* 画像形式は **JPG** と **BMP** をサポート
* 定数 **lcd.CENTER**、**lcd.BOTTOM**、**lcd.RIGHT** は x と y に使用できる
* **x** と **y** には負数も指定できます

* **scale**: 画像の拡大率
   * JPEGの場合は 0 から 3 までで、以下の拡大率になる: 1/(2^scale) (1/2, 1/4 or 1/8)
   * BMPの場合は 0 から 7 までで、以下の拡大率になる: 1/(scale+1)

* **type**: 画像形式 *lcd.JPG* または *lcd.BMP* 

### lcd.setwin(x, y, x1, y1)

表示枠を　 (x,y) - (x1,y1) の短形に設定する。

### lcd.resetwin()

表示枠をフルスクリーンにリセットする。

### lcd.savewin()

現在の表示枠設定をセーブする。

### lcd.restorewin()

前に savewin() でセーブした表示枠の設定を元に戻す。

### lcd.screensize()

LCD のサイズを (width, height) のタプルで返す。

~~LCDのサイズは320x240のはずであるが、現状ではなぜか(320, 320)が返る。~~

※ v0.3.0から正常に(320, 240)を返すようになった。

### lcd.winsize()

表示枠のサイズを (width, height) のタプルで返す。

~~こちらも ```lcd.setwin()``` で設定しないかぎりは(320, 320)が返ってしまう。~~

※ v0.3.2から正常にデフォルトで(320, 240)を返すようになった。

### lcd.hsb2rgb(hue, saturation, brightness)

HSB形式で指定した色を同等のRGB値に変換して返す。

パラメータ:

* **hue**: float: 色相 0 ~ 1.0未満
* **saturation**: float; 彩度 0 ~ 1.0
* **brightness**: float; 明度 0 ~ 1.0

### lcd.compileFont(file_name [,debug])

ソースフォントファイル(拡張子が **.c**)をバイナリのフォントファイル(拡張子が **.fon**)にコンパイルする。

*debug=True* であれば、コンパイルしたフォントの情報が表示される。

**tft** フォントから **c** ソース・ファイルを作成するには [ttf2c_vc2003.exe](https://github.com/loboris/MicroPython_ESP32_psRAM_LoBo/tree/master/MicroPython_BUILD/components/micropython/esp32/modules_examples/tft/font_tool/) プログラムが使える。手順は [README](https://github.com/loboris/MicroPython_ESP32_psRAM_LoBo/tree/master/MicroPython_BUILD/components/micropython/esp32/modules_examples/tft/font_tool/README.md) を参照。