クラス 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_charis 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です。
定数¶
フロー制御¶
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 のままとなります。