クラス UART -- 二重シリアル通信バス¶
UART は標準の UART/USART 二重シリアル通信プロトコルを実装しています。物理レベルでは RX と TX の2線で構成されています。通信の単位は 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文字を書き出す
1文字単位の読込み/書出しは次のようにします:
uart.readchar() # 1文字を読み込み、整数として返す
uart.writechar(42) # 1文字を書き出す
読み込めるものがあるかのチェックは次のようにします:
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
は1文字あたりのビット数で、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
です。
定数¶
フロー制御¶
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
の間、送信が一時停止します。タイムアウト期間内にバッファ全体が送信されなかった場合、タイムアウトが発生します。このメソッドは送信されたバイト数を返すため、必要に応じて残りのデータを送信することができます。タイムアウトが発生すると、1文字が 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
のままとなります。