chrome.serial

說明

使用 chrome.serial API 從連接至序列埠的裝置讀取資料，以及在該裝置上寫入資料。

權限

serial

類型

ConnectionInfo

屬性

  • bitrate

    號碼 選填

    詳情請參閱 ConnectionOptions.bitrate。如果使用非標準位元率，或查詢基礎裝置時發生錯誤，這個欄位可能會省略或不準確。

  • bufferSize

    數字

    查看「ConnectionOptions.bufferSize」

  • connectionId

    數字

    序列埠連線的 ID。

  • ctsFlowControl

    布林值 選填

    詳情請參閱 ConnectionOptions.ctsFlowControl。如果查詢基礎裝置時發生錯誤，可以省略這個欄位。

  • dataBits

    DataBits 選填

    詳情請參閱 ConnectionOptions.dataBits。如果查詢基礎裝置時發生錯誤，可以省略這個欄位。

  • 名稱

    字串

    查看「ConnectionOptions.name」

  • parityBit

    ParityBit 選填

    詳情請參閱 ConnectionOptions.parityBit。如果查詢基礎裝置時發生錯誤，可以省略這個欄位。

  • 已暫停

    布林值

    此標記用於註明連線是否遭到封鎖，無法觸發 onReceive 事件。

  • 永久

    布林值

    查看「ConnectionOptions.persistent」

  • receiveTimeout

    數字

    查看「ConnectionOptions.receiveTimeout」

  • sendTimeout

    數字

    查看「ConnectionOptions.sendTimeout」

  • stopBits

    StopBits 選填

    詳情請參閱 ConnectionOptions.stopBits。如果查詢基礎裝置時發生錯誤，可以省略這個欄位。

ConnectionOptions

屬性

  • bitrate

    號碼 選填

    要開啟的連線要求位元率。為確保與各種硬體相容，這個數字應與常見的位元率相符，例如 110、300、1200、2400、4800、9600、14400、19200、38400、57600、115200。當然，即使序列埠本身支援要求的位元率，也不保證連線至序列埠的裝置會支援該位元率。預設會傳遞 9600。

  • bufferSize

    號碼 選填

    用來接收資料的緩衝區大小。預設值為 4096。

  • ctsFlowControl

    布林值 選填

    此標記用於註明是否要啟用 RTS/CTS 硬體流量控制。預設值為 false。

  • dataBits

    DataBits 選填

    預設會傳遞 "eight"。

  • 名稱

    字串 選填

    與連線建立關聯的應用程式定義字串。

  • parityBit

    ParityBit 選填

    預設會傳遞 "no"。

  • 永久

    布林值 選填

    這個旗標會指出應用程式暫停時，是否應保持連線開啟狀態 (請參閱「管理應用程式生命週期」)。預設值為「false」。應用程式載入後，先前以 persistent=true 開啟的任何序列連線，都可以使用 getConnections 擷取。

  • receiveTimeout

    號碼 選填

    等待新資料的最長時間 (以毫秒為單位)，超過這個時間後，系統會發出含有「timeout」錯誤的 onReceiveError 事件。如果為零，連線就不會引發接收逾時錯誤。預設為 0。

  • sendTimeout

    號碼 選填

    等待 send 作業完成的時間上限 (以毫秒為單位)，超過這個時間後，系統會呼叫回呼並傳回「timeout」錯誤。如果為零，系統就不會觸發傳送逾時錯誤。預設為 0。

  • stopBits

    StopBits 選填

    預設會傳遞 "one"。

DataBits

列舉

「seven」

「eight」

DeviceControlSignals

屬性

  • cts

    布林值

    CTS (清除傳送)。

  • dcd

    布林值

    DCD (資料載波偵測) 或 RLSD (接收線路訊號/ 偵測)。

  • dsr

    布林值

    DSR (資料集已準備就緒)。

  • ri

    布林值

    RI (鈴聲指標)。

DeviceInfo

屬性

  • displayName

    字串 選填

    如果可以從主機驅動程式查詢，則為基礎裝置的使用者可讀顯示名稱。

  • 路徑

    字串

    裝置的系統路徑。這應做為 chrome.serial.connect 的 path 引數傳遞，以便連線至這部裝置。

  • productId

    號碼 選填

    如果可以判斷基礎裝置的 USB 產品 ID，則為該 ID。

  • vendorId

    號碼 選填

    如果可以判斷基礎裝置的 PCI 或 USB 供應商 ID，則為該 ID。

HostControlSignals

屬性

  • dtr

    布林值 選填

    DTR (資料終端機就緒)。

  • rts

    布林值 選填

    RTS (傳送要求)。

ParityBit

列舉

「no」

「odd」

「even」

ReceiveError

列舉

「已中斷連線」
連線已中斷。

「timeout」
receiveTimeout 毫秒內未收到任何資料。

"device_lost"
裝置很可能已與主機中斷連線。

「break」
裝置偵測到中斷條件。

「frame_error」
裝置偵測到影格錯誤。

「溢位」
發生字元緩衝區溢位。下一個字元會遺失。

「buffer_overflow」
發生輸入緩衝區溢位。輸入緩衝區沒有空間，或是在檔案結尾 (EOF) 字元後收到字元。

「parity_error」
裝置偵測到同位檢查錯誤。

「system_error」
系統發生錯誤，連線可能無法復原。

ReceiveErrorInfo

屬性

  • connectionId

    數字

    連線 ID。

  • 錯誤

    ReceiveError

    指出發生錯誤的錯誤代碼。

ReceiveInfo

屬性

  • connectionId

    數字

    連線 ID。

  • 資料

    ArrayBuffer

    收到的資料。

SendError

列舉

「已中斷連線」
連線已中斷。

「待處理」
已有一筆待處理的傳送交易。

「timeout」
傳送逾時。

「system_error」
系統發生錯誤，連線可能無法復原。

SendInfo

屬性

  • bytesSent

    數字

    傳送的位元組數。

  • 錯誤

    SendError 選用

    如果發生錯誤，則為錯誤代碼。

StopBits

列舉

「one」

「two」

方法

clearBreak()

Promise Chrome 45 以上版本 
chrome.serial.clearBreak(
  connectionId: number,
  callback?: function,
): Promise<boolean>

在指定連線上還原字元傳輸，並將傳輸線置於非中斷狀態。

參數

  • connectionId

    數字

    連線的 ID。

  • callback

    函式 選用

    callback 參數如下： 

    (result: boolean) => void

    • 結果

      布林值

傳回

  • Promise<boolean>

    Chrome 117 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

connect()

Promise 
chrome.serial.connect(
  path: string,
  options?: ConnectionOptions,
  callback?: function,
): Promise<ConnectionInfo>

連線至指定序列埠。

參數

  • 路徑

    字串

    要開啟的序列埠系統路徑。

  • 選項

    ConnectionOptions 選用

    通訊埠設定選項。

  • callback

    函式 選用

    callback 參數如下： 

    (connectionInfo: ConnectionInfo) => void

傳回

  • Promise<ConnectionInfo>

    Chrome 117 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

disconnect()

Promise 
chrome.serial.disconnect(
  connectionId: number,
  callback?: function,
): Promise<boolean>

中斷與序列埠的連線。

參數

  • connectionId

    數字

    已開啟連線的 ID。

  • callback

    函式 選用

    callback 參數如下： 

    (result: boolean) => void

    • 結果

      布林值

傳回

  • Promise<boolean>

    Chrome 117 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

flush()

Promise 
chrome.serial.flush(
  connectionId: number,
  callback?: function,
): Promise<boolean>

排清指定連線輸入和輸出緩衝區中的所有位元組。

參數

  • connectionId

    數字

  • callback

    函式 選用

    callback 參數如下： 

    (result: boolean) => void

    • 結果

      布林值

傳回

  • Promise<boolean>

    Chrome 117 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

getConnections()

Promise 
chrome.serial.getConnections(
  callback?: function,
): Promise<ConnectionInfo[]>

擷取應用程式目前開啟的序列埠連線清單。

參數

傳回

  • Promise<ConnectionInfo[]>

    Chrome 117 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

getControlSignals()

Promise 
chrome.serial.getControlSignals(
  connectionId: number,
  callback?: function,
): Promise<DeviceControlSignals>

擷取指定連線的控制信號狀態。

參數

傳回

  • Chrome 117 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

getDevices()

Promise 
chrome.serial.getDevices(
  callback?: function,
): Promise<DeviceInfo[]>

傳回系統上可用序列裝置的相關資訊。每次呼叫這個方法時，系統都會重新產生清單。

參數

  • callback

    函式 選用

    callback 參數如下： 

    (ports: DeviceInfo[]) => void

傳回

  • Promise<DeviceInfo[]>

    Chrome 117 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

getInfo()

Promise 
chrome.serial.getInfo(
  connectionId: number,
  callback?: function,
): Promise<ConnectionInfo>

擷取指定連線的狀態。

參數

  • connectionId

    數字

    已開啟連線的 ID。

  • callback

    函式 選用

    callback 參數如下： 

    (connectionInfo: ConnectionInfo) => void

傳回

  • Promise<ConnectionInfo>

    Chrome 117 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

send()

Promise 
chrome.serial.send(
  connectionId: number,
  data: ArrayBuffer,
  callback?: function,
): Promise<SendInfo>

將資料寫入指定連線。

參數

  • connectionId

    數字

    連線的 ID。

  • 資料

    ArrayBuffer

    要傳送的資料。

  • callback

    函式 選用

    callback 參數如下： 

    (sendInfo: SendInfo) => void

傳回

  • Promise<SendInfo>

    Chrome 117 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

setBreak()

Promise Chrome 45 以上版本 
chrome.serial.setBreak(
  connectionId: number,
  callback?: function,
): Promise<boolean>

暫停指定連線上的字元傳輸，並將傳輸線置於中斷狀態，直到呼叫 clearBreak 為止。

參數

  • connectionId

    數字

    連線的 ID。

  • callback

    函式 選用

    callback 參數如下： 

    (result: boolean) => void

    • 結果

      布林值

傳回

  • Promise<boolean>

    Chrome 117 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

setControlSignals()

Promise 
chrome.serial.setControlSignals(
  connectionId: number,
  signals: HostControlSignals,
  callback?: function,
): Promise<boolean>

設定指定連線的控制訊號狀態。

參數

  • connectionId

    數字

    連線的 ID。

  • 要傳送至裝置的訊號變更組合。

  • callback

    函式 選用

    callback 參數如下： 

    (result: boolean) => void

    • 結果

      布林值

傳回

  • Promise<boolean>

    Chrome 117 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

setPaused()

Promise 
chrome.serial.setPaused(
  connectionId: number,
  paused: boolean,
  callback?: function,
): Promise<void>

暫停或取消暫停開啟的連線。

參數

  • connectionId

    數字

    已開啟連線的 ID。

  • 已暫停

    布林值

    用於指出是否要暫停或取消暫停的旗標。

  • callback

    函式 選用

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 117 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

update()

Promise 
chrome.serial.update(
  connectionId: number,
  options: ConnectionOptions,
  callback?: function,
): Promise<boolean>

更新開啟的序列埠連線選項設定。

參數

  • connectionId

    數字

    已開啟連線的 ID。

  • 通訊埠設定選項。

  • callback

    函式 選用

    callback 參數如下： 

    (result: boolean) => void

    • 結果

      布林值

傳回

  • Promise<boolean>

    Chrome 117 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

事件

onReceive

chrome.serial.onReceive.addListener(
  callback: function,
)

從連線讀取資料時引發的事件。

參數

onReceiveError

chrome.serial.onReceiveError.addListener(
  callback: function,
)

執行階段等待序列埠資料時發生錯誤，就會引發這個事件。引發這個事件後，連線可能會設為 paused。"timeout" 錯誤不會暫停連線。

參數