【pySerial3.4官方文件】3、pySerial API
pySerial API
類
本地埠
類serial.Serial
__init__（port = None，baudrate = 9600，bytesize = EIGHTBITS，parity = PARITY_NONE，stopbits = STOPBITS_ONE，timeout = None，xonxoff = False，rtscts = False，write_timeout = None，dsrdtr = False，inter_byte_timeout = None，exclusive = None ）
| 引數： |
|
|---|---|
| 異常： |
|
在給出埠時，在建立物件時立即開啟埠。當埠是None並且需要連續呼叫時它不會開啟open()。
port是裝置名稱：取決於作業系統。例如 /dev/ttyUSB0在GNU / Linux或COM3Windows上。
引數波特率可以是標準值之一：50,75,110,134,150,200,300,600,1200,1800,2400,4800,9600,19200,38400,57600,115200。這些都得到了很好的支援所有平臺。
高於115200的標準值，例如：230400,460800,500000,576000,921600,1000000,1152000,1500000,2000000,2500000,3000000,3500000,4000000也適用於許多平臺和裝置。
某些平臺（GNU / Linux，MAC OSX> = Tiger，Windows）也支援非標準值。但是，即使在這些平臺上，某些串列埠也可能會拒絕非標準值。
引數超時的可能值，用於控制以下行為read()：
timeout = None：永遠等待/直到收到請求的位元組數timeout = 0：非阻塞模式，在任何情況下立即返回，返回零或更多，直到請求的位元組數timeout = x：set timeout toxseconds（float allowed）在請求的位元組數可用時立即返回，否則等到超時到期並返回之前收到的所有位元組。
write()預設情況下是阻塞，除非設定了write_timeout。有關可能的值，請參閱上面的超時列表。
請注意，可能不支援同時啟用兩種流控制方法（xonxoff和rtscts）。通常一次使用其中一種方法，而不是兩種方法。
並非所有平臺都支援dsrdtr（以靜默方式忽略）。將其設定為None具有其狀態遵循rtscts的效果。
還要考慮使用該函式serial_for_url()而不是直接建立Serial例項。
在版本2.5中更改：dsrdtr現在預設為False（而不是None）
版本3.0中已更改：不再支援數字作為埠引數
版本3.3中的新功能：exclusive標誌
open（）
注意
一旦開啟埠，某些OS和/或驅動程式可能會自動啟用RTS和/或DTR。有可能是在RTS / DTR毛刺時rts或dtr從它們的預設值（不同地設定True/啟用）。
注意
出於相容性原因，由於EINVAL（22）或ENOTTY（25）而在POSIX上應用rts或dtr失敗時未報告錯誤 。
close（）
立即關閉埠。
__del__（）
解構函式，釋放串列埠例項時的關閉埠。
SerialException應用於封閉埠時，可能會出現以下方法。
read（size = 1 ）
| 引數： | size - 要讀取的位元組數。 |
|---|---|
| 返回： | 從埠讀取的位元組數。 |
| 返回型別： | 位元組 |
從串列埠讀取大小位元組。如果設定了超時，則可能會根據請求返回較少的字元。沒有超時，它將阻塞，直到讀取所請求的位元組數。
在版本2.5中更改：返回bytes可用時的例項（Python 2.6和更新版本），str否則返回。
read_until（期望= LF，大小=無）
| 引數： |
|
|---|---|
| 返回： | 從埠讀取的位元組數。 |
| 返回型別： |
讀取直到找到預期的序列（預設為'\ n'），超出大小或發生超時。如果設定了超時，則可能會根據請求返回較少的字元。沒有超時，它將阻塞，直到讀取所請求的位元組數。
在版本2.5中更改：返回bytes可用時的例項（Python 2.6和更新版本），str否則返回。
write（資料）
| 引數： | data - 要傳送的資料。 |
|---|---|
| 返回： | 寫入的位元組數。 |
| 返回型別： | INT |
| 異常： | SerialTimeoutException - 如果為埠配置了寫入超時並且超過了時間。 |
將位元組資料寫入埠。這應該是型別bytes （或相容，如bytearray或memoryview）。必須對Unicode字串進行編碼（例如'hello'.encode('utf-8'）。
在2.5版本中更改：接受的情況下，bytes和bytearray（Python的2.6和更高版本）和可用時str除外。
在版本2.5中更改：None在先前版本中返回寫入。
flush（）
像物件一樣重新整理檔案。在這種情況下，請等待所有資料寫入。
in_waiting
| Getter： | 獲取輸入緩衝區中的位元組數 |
|---|---|
| 型別： | INT |
返回接收緩衝區中的位元組數。
在3.0版中更改：從更改為屬性inWaiting()
out_waiting
| Getter： | 獲取輸出緩衝區中的位元組數 |
|---|---|
| 型別： | INT |
| 平臺： | POSIX |
| 平臺： | 視窗 |
返回輸出緩衝區中的位元組數。
在2.7版中更改:(已新增Posix支援）
在3.0版中更改：從更改為屬性outWaiting()
reset_input_buffer（）
重新整理輸入緩衝區，丟棄其所有內容。
在3.0版中更改：從中重新命名flushInput()
reset_output_buffer（）
清除輸出緩衝區，中止當前輸出並丟棄緩衝區中的所有內容。
請注意，對於某些USB序列介面卡，這可能只會重新整理OS的緩衝區，而不會重新整理USB部件中可能存在的所有資料。
在3.0版中更改：從中重新命名flushOutput()
send_break（持續時間= 0.25 ）
| 引數： | duration（float） - 啟用BREAK條件的時間。 |
|---|
傳送休息條件。定時，在給定的持續時間後返回空閒狀態。
break_condition
| Getter： | |
|---|---|
| Setter： | 控制BREAK狀態 |
| 型別： | 布林 |
設定為True啟用BREAK條件時，否則禁用。控制TXD。啟用時，無法進行傳輸。
rts
| Setter： | 設定RTS線的狀態 |
|---|---|
| Getter： | 返回RTS行的狀態 |
| 型別： | 布林 |
將RTS線設定為指定的邏輯電平。可以在開啟串列埠之前分配該值，然後應用該值 open()（有限制，請參閱參考資料open()）。
dtr
| Setter： | 設定DTR線的狀態 |
|---|---|
| Getter： | 返回DTR線的狀態 |
| 型別： | 布林 |
將DTR線設定為指定的邏輯電平。可以在開啟串列埠之前分配該值，然後應用該值 open()（有限制，請參閱參考資料open()）。
只讀屬性：
name
| Getter： | 裝置名稱。 |
|---|---|
| 型別： | 海峽 |
2.5版中的新功能。
cts
| Getter： | 獲取CTS線的狀態 |
|---|---|
| 型別： | 布林 |
返回CTS線的狀態。
dsr
| Getter： | 獲取DSR行的狀態 |
|---|---|
| 型別： | 布林 |
返回DSR行的狀態。
ri
| Getter： | 獲取RI線的狀態 |
|---|---|
| 型別： | 布林 |
返回RI線的狀態。
cd
| Getter： | 獲取CD行的狀態 |
|---|---|
| 型別： | 布林 |
返回CD行的狀態
is_open
| Getter： | 獲取串列埠的狀態，無論是否開啟。 |
|---|---|
| 型別： | 布林 |
可以將新值分配給以下屬性（屬性），即使在此時開啟埠，也會重新配置埠：
port
| 型別： | 海峽 |
|---|
讀或寫埠。當埠已開啟時，它將關閉並使用新設定重新開啟。
baudrate
| Getter： | 獲取當前波特率 |
|---|---|
| Setter： | 設定新的波特率 |
| 型別： | INT |
讀取或寫入當前波特率設定。
bytesize
| Getter： | 獲取當前位元組大小 |
|---|---|
| Setter： | 設定新的位元組大小。可能的值： FIVEBITS，SIXBITS，SEVENBITS， EIGHTBITS |
| 型別： | INT |
讀取或寫入當前資料位元組大小設定。
parity
| Getter： | 獲取當前奇偶校驗設定 |
|---|---|
| 二傳手： | 設定新的奇偶校驗模式 可能的值： PARITY_NONE，PARITY_EVEN，，PARITY_ODDPARITY_MARKPARITY_SPACE |
讀取或寫入當前奇偶校驗設定。
stopbits
| Getter： | 獲取當前停止位設定 |
|---|---|
| 二傳手： | 設定新的停止位設定。可能的值： STOPBITS_ONE，STOPBITS_ONE_POINT_FIVE，STOPBITS_TWO |
讀或寫當前停止位寬設定。
timeout
| Getter： | 獲取當前讀取超時設定 |
|---|---|
| Setter： | 設定讀取超時 |
| 型別： | 浮點（秒） |
讀取或寫入當前讀取超時設定。
write_timeout
| Getter： | 獲取當前寫入超時設定 |
|---|---|
| Setter： | 設定寫入超時 |
| 型別： | 浮點（秒） |
讀或寫當前寫超時設定。
在3.0版中更改：從中重新命名writeTimeout
inter_byte_timeout
| Getter： | 獲取當前的位元組間超時設定 |
|---|---|
| Setter： | 禁用（None）或啟用位元組間超時 |
| 型別： | 浮動或無 |
讀取或寫入當前的位元組間超時設定。
在3.0版中更改：從中重新命名interCharTimeout
xonxoff
| Getter： | 獲取當前的軟體流控制設定 |
|---|---|
| Setter： | 啟用或禁用軟體流控制 |
| 型別： | 布林 |
讀取或寫入當前軟體流量控制速率設定。
rtscts
| Getter： | 獲取當前的硬體流控制設定 |
|---|---|
| Setter： | 啟用或禁用硬體流控制 |
| 型別： | 布林 |
讀取或寫入當前硬體流控制設定。
dsrdtr
| Getter： | 獲取當前的硬體流控制設定 |
|---|---|
| Setter： | 啟用或禁用硬體流控制 |
| 型別： | 布林 |
讀取或寫入當前硬體流控制設定。
rs485_mode
| Getter： | 獲取當前的RS485設定 |
|---|---|
| Setter： | 禁用（None）或啟用RS485設定 |
| 型別： | rs485.RS485Settings 要麼 None |
| 平臺： | Posix（Linux，有限的硬體組） |
| 平臺： | Windows（只有TX上的RTS可能） |
配置RS485支援的屬性。當設定為rs485.RS485SettingsOS 的例項 並由OS支援時，RTS將在傳送資料時處於活動狀態，否則將處於非活動狀態（用於接收）。本 rs485.RS485Settings類提供支援的在某些平臺上的其他設定。
版本3.0中的新功能。
還提供了以下常量：
BAUDRATES
有效波特率列表。該列表可能是不完整的，因此裝置也可以支援更高和/或中間的波特率（只讀）。
BYTESIZES
裝置的有效位元組大小列表（只讀）。
PARITIES
裝置的有效奇偶校驗列表（只讀）。
STOPBITS
裝置的有效停止位寬列表（只讀）。
以下方法用於與io庫相容。
readable（）
| 返回： | 真正 |
|---|
2.5版中的新功能。
writable（）
| 返回： | 真正 |
|---|
2.5版中的新功能。
seekable（）
| 返回： | 假 |
|---|
2.5版中的新功能。
readinto（b ）
| 引數： | b - bytearray或陣列例項 |
|---|---|
| 返回： | 讀取的位元組數 |
將len（b）位元組讀入b並返回讀取的位元組數。bytearray
2.5版中的新功能。
readline（size = -1 ）
通過提供 io.IOBase.readline()
readlines（提示= -1 ）
writelines（行）
埠設定可以作為字典讀取和寫入。下面的鍵被支援：write_timeout，inter_byte_timeout，dsrdtr，baudrate，timeout，parity，bytesize， rtscts，stopbits，xonxoff
get_settings（）
| 返回： | 具有當前埠設定的字典。 |
|---|---|
| 返回型別： | 字典 |
獲取包含埠設定的字典。這對於備份當前設定非常有用，以便以後可以使用它們進行恢復apply_settings()。
請注意，控制線的狀態（RTS / DTR）不是設定的一部分。
2.5版中的新功能。
在3.0版中更改：從中重新命名getSettingsDict
apply_settings（d ）
| 引數： | d（字典） - 帶埠設定的字典。 |
|---|
應用由...建立的字典get_settings()。僅應用更改，並且當缺少鍵時，表示設定保持不變。
請注意，控制線（RTS / DTR）不會更改。
2.5版中的新功能。
在3.0版中更改：從中重新命名applySettingsDict
該類可以用作上下文管理器。離開上下文時，串列埠將關閉。
__enter__（）
| 返回： | 序列例項 |
|---|
返回with語句中使用的例項。
例：
>>> with serial.serial_for_url(port) as s:
... s.write(b'hello')
埠自動開啟：
>>> port = serial.Serial()
>>> port.port = '...'
>>> with port as s:
... s.write(b'hello')
這也意味著with每次開啟和關閉埠時都可以重複使用語句。
版本3.4中已更改：埠自動開啟
__exit__（exc_type，exc_val，exc_tb ）
關閉串列埠（不處理異常__exit__）。
平臺特定方法。
警告
使用以下方法和屬性的程式無法移植到其他平臺！
nonblocking（）
| 平臺： | POSIX |
|---|
從版本3.2開始不推薦使用：串列埠已在此模式下開啟。這種方法不需要也不會消失。
fileno（）
| 平臺： | POSIX |
|---|---|
| 返回： | 檔案描述符。 |
返回此物件開啟的埠的檔案描述符編號。與串列埠一起使用時非常有用select。
set_input_flow_control（啟用）
| 平臺： | POSIX |
|---|---|
| 引數： | enable（bool） - 設定流量控制狀態。 |
手動控制流程 - 啟用軟體流控制時。
這會將XON（true）和XOFF（false）傳送到其他裝置。
版本2.7中的新功能:(添加了Posix支援）
在3.0版中更改：從中重新命名flowControlOut
set_output_flow_control（啟用）
| 平臺： | Posix（硬體和軟體流量控制） |
|---|---|
| 平臺： | Windows（僅限SW流控制） |
| 引數： | enable（bool） - 設定流量控制狀態。 |
手動控制傳出資料流 - 啟用硬體或軟體流控制時。
呼叫時將暫停傳送，呼叫False時將啟用傳送True。
在2.7版中更改:(在Posix上重新命名，函式被呼叫flowControl）
在3.0版中更改：從中重新命名setXON
cancel_read（）
| 平臺： | POSIX |
|---|---|
| 平臺： | 視窗 |
從另一個執行緒取消掛起的讀取操作。阻塞 read()呼叫立即中止。read()不會報告任何錯誤，但會返回到該點收到的所有資料（類似於超時）。
在Posix上，對cancel_read（）的呼叫可能會取消將來的read()呼叫。
版本3.1中的新功能。
cancel_write（）
| 平臺： | POSIX |
|---|---|
| 平臺： | 視窗 |
從另一個執行緒取消掛起的寫操作。該 write()方法將立即返回（未指示錯誤）。但是，OS可能仍在從緩衝區傳送，reset_output_buffer()可能需要單獨呼叫 。
在Posix上，對cancel_write（）的呼叫可能會取消將來的write()呼叫。
版本3.1中的新功能。
注意
以下成員已棄用，將在以後的版本中刪除。
portstr
從版本2.5開始不推薦使用：name改為使用
inWaiting（）
自3.0版以來已棄用：請參閱in_waiting
isOpen（）
自3.0版以來已棄用：請參閱is_open
writeTimeout
自3.0版以來已棄用：請參閱write_timeout
interCharTimeout
自3.0版以來已棄用：請參閱inter_byte_timeout
sendBreak（持續時間= 0.25 ）
自3.0版以來已棄用：請參閱send_break()
flushInput（）
自3.0版以來已棄用：請參閱reset_input_buffer()
flushOutput（）
自3.0版以來已棄用：請參閱reset_output_buffer()
setBreak（level = True ）
自3.0版以來已棄用：請參閱break_condition
setRTS（level = True ）
自3.0版以來已棄用：請參閱rts
setDTR（level = True ）
自3.0版以來已棄用：請參閱dtr
getCTS（）
自3.0版以來已棄用：請參閱cts
getDSR（）
自3.0版以來已棄用：請參閱dsr
getRI（）
自3.0版以來已棄用：請參閱ri
getCD（）
自3.0版以來已棄用：請參閱cd
getSettingsDict（）
自3.0版以來已棄用：請參閱get_settings()
applySettingsDict（d ）
自3.0版以來已棄用：請參閱apply_settings()
outWaiting（）
自3.0版以來已棄用：請參閱out_waiting
setXON（level = True ）
自3.0版以來已棄用：請參閱set_output_flow_control()
flowControlOut（啟用）
自3.0版以來已棄用：請參閱set_input_flow_control()
rtsToggle
| 平臺： | 視窗 |
|---|
用於配置RTS切換控制設定的屬性。當OS啟用並支援時，RTS將在資料可用時處於活動狀態，如果沒有可用資料則處於非活動狀態。
版本2.6中的新功能。
版本3.0中已更改:(已刪除，請參閱rs485_mode）
實現細節：一些屬性和函式由類提供，serial.SerialBase它們io.RawIOBase 由平臺特定類繼承，有些由上面提到的基類繼承。
RS485支援
本Serial類有一個Serial.rs485_mode屬性，它允許啟用在某些平臺上RS485具體的支援。目前支援Windows和Linux（僅少數裝置）。
Serial.rs485_mode需要設定為rs485.RS485Settings啟用或None禁用此功能的例項 。
用法：
import serial
import serial.rs485
ser = serial.Serial(...)
ser.rs485_mode = serial.rs485.RS485Settings(...)
ser.write(b'hello')
有一個子類rs485.RS485可用於模擬常規串列埠上的RS485支援（serial.rs485需要匯入）。
類rs485.RS485Settings
包含某些平臺支援的RS485特定設定的類。
版本3.0中的新功能。
__init__(rts_level_for_tx=True, rts_level_for_rx=False, loopback=False, delay_before_tx=None, delay_before_rx=None):
| 引數： |
|---|