このドキュメンテーションは、MicroPython の最新開発ブランチのためのものです。リリースバージョンでは利用できない機能に言及することがあります。

特定のリリースのドキュメントをお探しの場合は、左側のドロップダウンメニューを使って、望みのバージョンを選択します。

クラス UART -- 二重シリアル通信バス

UART は標準の UART/USART 二重シリアル通信プロトコルを実装しています。物理レベルでは RX と TX の２線で構成されています。通信の単位は 8 または 9 ビット幅の文字です(string 型の文字と混同しないでください)。

UART オブジェクトは以下をように作成、初期化できます:

from pyb import UART

uart = UART(1, 9600)                         # 指定したボーレートで初期化
uart.init(9600, bits=8, parity=None, stop=1) # 指定したパラメータで初期化

bits には 7, 8, 9 を指定できます。parity には None, 0 (偶数), 1 (奇数) を指定できます。stop には 1 か 2 を指定できます

注記: parity=None の場合、bits には 8 か 9 のみを指定できます。parity を有効にすると bits には 7 か 8 のみを指定できます。

UART オブジェクトはストリーム(stream)オブジェクトのように機能し、読み書きは標準のストリームメソッドを使って行われます。

uart.read(10)       # 10文字を読み込んで、bytes 型オブジェクトを返す
uart.read()         # 可能な限り文字を読み込む
uart.readline()     # 1行を読み込む
uart.readinto(buf)  # 読み込んで、与えたバッファに格納
uart.write('abc')   # 3文字を書き出す

１文字単位の読込み/書出しは次のようにします:

uart.readchar()     # １文字を読み込み、整数として返す
uart.writechar(42)  # １文字を書き出す

読み込めるものがあるかのチェックは次のようにします:

uart.any()          # 読込みを待機している文字数を返す

注記: ストリーム関数 read, write などは MicroPython v1.3.4 で新しく追加されました。それ以前のバージョンでは uart.send と uart.recv を使います。

コンストラクタ

class pyb.UART(bus, ...)

指定したバス上に UART オブジェクトを構築します。Pyboard のバスは 1-4, 6, 'XA', 'XB', 'YA', 'YB' のいずれかになります。Pyboard Lite のバスは 1, 2, 6, 'XB', 'YA' のいずれかになります。Pyboard D のバスは 1-4, 'XA', 'YA', 'YB' のいずれかになります。追加のパラメータを指定しない場合、UART オブジェクトは作成されますが初期化はされません(以前のバスの設定が残っている場合は、それを引き継ぎます)。追加の引数が指定された場合、バスが初期化されます。初期化のパラメータについては init を参照してください。

Pyboard 上の UART バスの物理ピン配置は次のとおりです:

UART(4) UART('XA'): (TX, RX) = (X1, X2) = (PA0, PA1)

UART(1) UART('XB'): (TX, RX) = (X9, X10) = (PB6, PB7)

UART(6) UART('YA'): (TX, RX) = (Y1, Y2) = (PC6, PC7)

UART(3) UART('YB'): (TX, RX) = (Y9, Y10) = (PB10, PB11)

UART(2): (TX, RX) = (X3, X4) = (PA2, PA3)

Pyboard Lite は UART(1), UART(2), UART(6) のみをサポートします。物理ピン配置は次のとおりです:

UART(1) UART('XB'): (TX, RX) = (X9, X10) = (PB6, PB7)

UART(6) UART('YA'): (TX, RX) = (Y1, Y2) = (PC6, PC7)

UART(2): (TX, RX) = (X1, X2) = (PA2, PA3)

Pyboard Dは UART(1), UART(2), UART(3), UART(4) のみをサポートします。物理ピン配置は次のとおりです:

UART(4) UART('XA'): (TX, RX) = (X1, X2) = (PA0, PA1)

UART(1) UART('YA'): (TX, RX) = (Y1, Y2) = (PA9, PA10)

UART(3) UART('YB'): (TX, RX) = (Y9, Y10) = (PB10, PB11)

UART(2): (TX, RX) = (X3, X4) = (PA2, PA3)

注記: Pyboard D では UART(1) が YA に配置されています。一方、Pyboard および Pyboard Lite では UART(1) が XB 、 UART(6) は YA に配置されています。

メソッド

UART.init(baudrate, bits=8, parity=None, stop=1, *, timeout=0, flow=0, timeout_char=0, read_buf_len=64)

与えたパラメータで UART バスを初期化します。

baudrate はクロックレートです。

bits は１文字あたりのビット数で、7, 8, 9 を指定できます。

parity はパリティビットで、 None, 0 (偶数), 1 (奇数)を指定できます。

stop はストップビットの数で、1 または 2 を指定できます。

flow はフロー制御の種別です。 0, UART.RTS, UART.CTS, UART.RTS | UART.CTS のいずれかを指定できます。

timeout は最初の文字の読み書きを待つ時間を指定します(ミリ秒単位)。

timeout_char is the timeout in milliseconds to wait between characters while writing or reading.

read_buf_len は読込みバッファの文字長を指定します(0 に設定するとバッファが無効になります)。

このメソッドは、ボーレートを希望値の 5% 以内に設定できなかった場合に例外を発生させます。最小ボーレートは、UART が属するバスの周波数によって決まります。UART(1) と UART(6) は APB2 に属し、その他の UART は APB1 に属します。デフォルトのバス周波数では、UART(1) と UART(6) の最小ボーレートは 1300、その他の UART の最小ボーレートは 650 です。より低いボーレートを使用するには pyb.freq を使ってバスの周波数を下げてください。

注記: parity=None の場合、bits には 8 か 9 のみを指定できます。parity を有効にすると bits には 7 か 8 のみを指定できます。

UART.deinit(): UART バスをオフにします。

UART.any(): 読込みを待機しているバイト数を返します(待機しているものがない場合は 0 を返します)。

UART.read([nbytes])

文字を読み込みます。 nbytes が指定されている場合、最大 nbytes バイトを読み込みます。 nbytes 分のデータがバッファ内に存在する場合は即座に返します。そうでない場合、十分なデータが到着するかタイムアウトするまで待機します。

nbytes が指定されていない場合、可能な限り多くのデータを読み込みます。タイムアウトするまでデータを取得し続け、時間切れになった時点で返します。

注記: 9ビット文字モードの場合、各文字は2バイトで表現されます。このため nbytes は偶数である必要があります。読み込む文字数は nbytes/2 になります。

戻り値: 読み込んだバイト列を含む bytes 型オブジェクト。タイムアウト時は None を返します。

UART.readchar()

バスから単一文字を受信します。

戻り値: 読み込んだ文字(整数として返します)。タイムアウト時は -1 を返します。

UART.readinto(buf[, nbytes])

buf にバイトを読み込みます。 nbytes が指定されている場合は、最大でそのバイト数を読み込みます。nbytes を指定しなかった場合は、最大で len(buf) バイト数を読み込みます。

戻り値: 読み込んで buf に格納したバイト数。タイムアウト時は None を返します。

UART.readline()

改行で終わる行を読み込みます。そのような行が存在する場合は即座に返します。タイムアウトした場合、改行がなくても利用可能なデータをすべて返します。

戻り値: 読み込んだ行。データが存在せずにタイムアウトが発生した場合は None を返します。

UART.write(buf)

バスにバッファ内のバイトデータを書き出します。7ビットまたは8ビットの文字の場合、各バイトが1文字として扱われます。9ビットの文字の場合、1文字につき2バイト(リトルエンディアン)を使い、 buf は偶数バイト数を含む必要があります。

戻り値: 書き出したバイト数。タイムアウトが発生し、1バイトも書き出せなかった場合は None を返します。

UART.writechar(char): バスに単一文字を書き出します。 char には書き出す整数値を指定します。戻り値は None です。CTS フロー制御を使っている場合の動作については、以下の注意事項を参照してください。

UART.sendbreak(): バスにブレークコンディションを送信します。これは、バスを13ビット分の時間だけ low にします。戻り値は None です。

定数

UART.RTS
UART.CTS: フロー制御の種別。

フロー制御

Pyboard V1 と V1.1 では UART(2) と UART(3) は RTS/CTS ハードウェアフロー制御をサポートし、対応するピンは次のとおりです:

UART(2): (TX, RX, nRTS, nCTS) = (X3, X4, X2, X1) = (PA2, PA3, PA1, PA0)

UART(3): (TX, RX, nRTS, nCTS) = (Y9, Y10, Y7, Y6) = (PB10, PB11, PB14, PB13)

Pyboard Lite では UART(2) のみフロー制御をサポートし、ピン配置は次のとおりです:

(TX, RX, nRTS, nCTS) = (X1, X2, X4, X3) = (PA2, PA3, PA1, PA0)

以降の段落において「ターゲット」という用語は、UART に接続されているデバイスを指すものとします。

UART の init() メソッドで flow に UART.RTS と UART.CTS のいずれか、または両方を指定すると、対応するフロー制御ピンが有効になります。 nRTS はアクティブ low の出力、 nCTS はプルアップ付きのアクティブ low の入力になります。フロー制御を有効にするには、Pyboard の nCTS をターゲットデバイスの nRTS に接続し、Pyboard の nRTS をターゲットの nCTS に接続する必要があります。

CTS: ターゲットが Pyboard の転送を制御

CTS フロー制御が有効な場合、書出しの動作は次のようになります:

Pyboard の UART.write(buf) メソッドが呼び出されると、 nCTS が False の間、送信が一時停止します。タイムアウト期間内にバッファ全体が送信されなかった場合、タイムアウトが発生します。このメソッドは送信されたバイト数を返すため、必要に応じて残りのデータを送信することができます。タイムアウトが発生すると、１文字が UART 内に保持され、 nCTS の状態を待ちます。この文字を構成するバイト数も、戻り値に含まれます。

UART.writechar() を nCTS が False の状態で呼び出した場合、ターゲットが適切なタイミングで nCTS をアサートしない限り、このメソッドはタイムアウトします。タイムアウトすると OSError 116 が発生します。ターゲットが nCTS をアサートすると、その時点で文字が送信されます。

RTS: Pyboard がターゲットの転送を制御

RTS フロー制御が有効な場合の動作は次のようになります:

バッファリングされた入力が使われている場合(read_buf_len > 0)、受信した文字はバッファに格納されます。バッファが満杯になると、次の文字が到着した時点で nRTS が False になります。これにより、ターゲットは送信を停止する必要があります。バッファからデータが読み込まれると nRTS は True に戻ります。

any() メソッドはバッファ内のバイト数を返すことに注意してください。バッファの長さを N バイトと仮定します。バッファが満杯になり、さらに 1 文字が到着すると nRTS は False になります。 any() はこの時点で N を返します。その後、データが読み込まれると、追加の文字がバッファに格納され、次回の any() 呼び出し時に含まれます。

バッファリングされた入力が使われていない場合(read_buf_len == 0)、文字が到着すると nRTS が False になり、その文字が読み込まれるまで nRTS は False のままとなります。