Web Serial API, web sitelerinin seri cihazlarla iletişim kurmasına olanak tanır.
Web Serial API nedir?
Seri bağlantı noktası, verileri bayt bayt gönderip almaya olanak tanıyan iki yönlü bir iletişim arayüzüdür.
Web Serial API, web sitelerinin JavaScript ile seri cihazlardan veri okumasına ve bu cihazlara veri yazmasına olanak tanır. Seri cihazlar, kullanıcının sistemindeki seri bağlantı noktası veya seri bağlantı noktasını taklit eden çıkarılabilir USB ve Bluetooth cihazlar üzerinden bağlanır.
Diğer bir deyişle Web Serial API, web sitelerinin mikrodenetleyiciler ve 3D yazıcılar gibi seri cihazlarla iletişim kurmasına olanak tanıyarak web ile fiziksel dünya arasında köprü oluşturur.
İşletim sistemleri, uygulamaların bazı seri bağlantı noktalarıyla iletişim kurarken düşük düzeyli USB API yerine daha yüksek düzeyli seri API'lerini kullanmasını gerektirdiğinden bu API, WebUSB ile de mükemmel bir uyum sağlar.
Önerilen kullanım alanları
Eğitim, hobi ve endüstri sektörlerinde kullanıcılar bilgisayarlarına çevre birimleri bağlar. Bu cihazlar genellikle özel yazılımlar tarafından kullanılan seri bağlantı üzerinden mikrodenetleyiciler tarafından kontrol edilir. Bu cihazları kontrol etmek için kullanılan bazı özel yazılımlar web teknolojisiyle geliştirilmiştir:
Bazı durumlarda web siteleri, kullanıcıların manuel olarak yüklediği bir aracı uygulaması aracılığıyla cihazla iletişim kurar. Diğerlerinde ise uygulama, Electron gibi bir çerçeve aracılığıyla paketlenmiş bir uygulama olarak yayınlanır. Bazı durumlarda ise kullanıcının, derlenmiş bir uygulamayı USB flash sürücü aracılığıyla cihaza kopyalama gibi ek bir adım uygulaması gerekir.
Tüm bu durumlarda, web sitesi ile kontrol ettiği cihaz arasında doğrudan iletişim sağlanarak kullanıcı deneyimi iyileşir.
Mevcut durum
Step | Durum |
---|---|
1. Açıklayıcı oluşturun | Tamamlandı |
2. İlk spesifikasyon taslağını oluşturun | Tamamlandı |
3. Geri bildirim toplayın ve tasarımda iterasyon yapın | Tamamlandı |
4. Kaynak denemesi | Tamamlandı |
5. Lansman | Tamamlandı |
Web Serial API'yi kullanma
Özellik algılama
Web Serial API'nin desteklenip desteklenmediğini kontrol etmek için:
if ("serial" in navigator) {
// The Web Serial API is supported.
}
Seri bağlantı noktası açma
Web Serial API, tasarım gereği asenkrondur. Bu sayede, web sitesi kullanıcı arayüzü, giriş beklerken engellenmez. Seri veriler herhangi bir zamanda alınabileceğinden ve dinlenmesi gerektiğinden bu durum önemlidir.
Seri bağlantı noktasını açmak için önce bir SerialPort
nesnesine erişin. Bunun için, dokunma veya fare tıklaması gibi bir kullanıcı hareketine yanıt olarak navigator.serial.requestPort()
işlevini çağırarak kullanıcıdan tek bir seri bağlantı noktası seçmesini isteyebilir ya da web sitesinin erişmesine izin verilen seri bağlantı noktalarının listesini döndüren navigator.serial.getPorts()
işlevinden birini seçebilirsiniz.
document.querySelector('button').addEventListener('click', async () => {
// Prompt user to select any serial port.
const port = await navigator.serial.requestPort();
});
// Get all serial ports the user has previously granted the website access to.
const ports = await navigator.serial.getPorts();
navigator.serial.requestPort()
işlevi, filtreleri tanımlayan isteğe bağlı bir nesne değişmez değeri alır. Bunlar, USB üzerinden bağlı herhangi bir seri cihazı zorunlu USB tedarikçisiyle (usbVendorId
) ve isteğe bağlı USB ürün tanımlayıcılarıyla (usbProductId
) eşleştirmek için kullanılır.
// Filter on devices with the Arduino Uno USB Vendor/Product IDs.
const filters = [
{ usbVendorId: 0x2341, usbProductId: 0x0043 },
{ usbVendorId: 0x2341, usbProductId: 0x0001 }
];
// Prompt user to select an Arduino Uno device.
const port = await navigator.serial.requestPort({ filters });
const { usbProductId, usbVendorId } = port.getInfo();
requestPort()
çağrıldığında, kullanıcıdan cihaz seçmesi istenir ve SerialPort
nesnesi döndürülür. Bir SerialPort
nesnesi oluşturduktan sonra, port.open()
işlevini istenen baud hızıyla çağırmak seri bağlantı noktasını açar. baudRate
sözlük üyesi, verilerin seri hat üzerinden ne kadar hızlı gönderildiğini belirtir. Saniye başına bit (bps) cinsinden ifade edilir. Bu parametre yanlış belirtilirse gönderdiğiniz ve aldığınız tüm veriler anlamsız olacaktır. Bu nedenle, doğru değeri öğrenmek için cihazınızın belgelerini inceleyin. Seri bağlantı noktasını taklit eden bazı USB ve Bluetooth cihazlarda bu değer, taklit tarafından yok sayıldığı için herhangi bir değere güvenli bir şekilde ayarlanabilir.
// Prompt user to select any serial port.
const port = await navigator.serial.requestPort();
// Wait for the serial port to open.
await port.open({ baudRate: 9600 });
Seri bağlantı noktası açarken aşağıdaki seçeneklerden herhangi birini de belirtebilirsiniz. Bu seçenekler isteğe bağlıdır ve kullanışlı varsayılan değerlere sahiptir.
dataBits
: Kare başına veri bit sayısı (7 veya 8).stopBits
: Bir karenin sonunda bulunan durdurma bitlerinin sayısı (1 veya 2).parity
: Eşlik modu ("none"
,"even"
veya"odd"
).bufferSize
: Oluşturulması gereken okuma ve yazma arabelleklerinin boyutu (16 MB'tan küçük olmalıdır).flowControl
: Akış denetimi modu ("none"
veya"hardware"
).
Seri bağlantı noktasından okuma
Web Serial API'deki giriş ve çıkış akışları Streams API tarafından yönetilir.
Seri bağlantısı kurulduktan sonra SerialPort
nesnesinin readable
ve writable
özellikleri bir ReadableStream ve WritableStream döndürür. Bunlar, seri cihazdan veri almak ve seri cihaza veri göndermek için kullanılır. Her ikisi de veri aktarımı için Uint8Array
örnekleri kullanır.
Seri cihazdan yeni veri geldiğinde port.readable.getReader().read()
, value
ve done
boole türü iki özelliği eşzamansız olarak döndürür. done
doğruysa seri bağlantı noktası kapatılmış veya artık veri gelmiyordur. port.readable.getReader()
çağrısı yapıldığında bir okuyucu oluşturulur ve readable
bu okuyucuya kilitlenir. readable
kilitliyken seri bağlantı noktası kapatılamaz.
const reader = port.readable.getReader();
// Listen to data coming from the serial device.
while (true) {
const { value, done } = await reader.read();
if (done) {
// Allow the serial port to be closed later.
reader.releaseLock();
break;
}
// value is a Uint8Array.
console.log(value);
}
Arabellek taşması, çerçeveleme hataları veya parite hataları gibi bazı koşullarda, seri bağlantı noktası okumayla ilgili bazı önemli olmayan hatalar oluşabilir. Bunlar istisna olarak atılır ve öncekinin üzerine port.readable
değerini kontrol eden başka bir döngü ekleyerek yakalanabilir. Bu işe yarar çünkü hatalar önemli olmadığı sürece otomatik olarak yeni bir ReadableStream oluşturulur. Seri cihazın kaldırılması gibi kritik bir hata meydana gelirse port.readable
null olur.
while (port.readable) {
const reader = port.readable.getReader();
try {
while (true) {
const { value, done } = await reader.read();
if (done) {
// Allow the serial port to be closed later.
reader.releaseLock();
break;
}
if (value) {
console.log(value);
}
}
} catch (error) {
// TODO: Handle non-fatal read error.
}
}
Seri cihaz metin gönderirse port.readable
değerini aşağıda gösterildiği gibi bir TextDecoderStream
üzerinden aktarabilirsiniz. TextDecoderStream
, tüm Uint8Array
parçalarını alıp dizelere dönüştüren bir dönüşüm akışı'dır.
const textDecoder = new TextDecoderStream();
const readableStreamClosed = port.readable.pipeTo(textDecoder.writable);
const reader = textDecoder.readable.getReader();
// Listen to data coming from the serial device.
while (true) {
const { value, done } = await reader.read();
if (done) {
// Allow the serial port to be closed later.
reader.releaseLock();
break;
}
// value is a string.
console.log(value);
}
"Bring Your Own Araffer" (Kendi Arabelleğinizi Getir) okuyucuyu kullanarak akıştan okuma yaptığınızda belleğin nasıl ayrılacağını kontrol edebilirsiniz. ReadableStreamBYOBReader arayüzünü almak için port.readable.getReader({ mode: "byob" })
'ü çağırın ve read()
'i çağırırken kendi ArrayBuffer
'ınızı sağlayın. Chrome 106 veya sonraki sürümlerde Web Serial API'nin bu özelliği desteklediğini unutmayın.
try {
const reader = port.readable.getReader({ mode: "byob" });
// Call reader.read() to read data into a buffer...
} catch (error) {
if (error instanceof TypeError) {
// BYOB readers are not supported.
// Fallback to port.readable.getReader()...
}
}
value.buffer
içindeki arabelleğin nasıl yeniden kullanılacağına dair bir örnek aşağıda verilmiştir:
const bufferSize = 1024; // 1kB
let buffer = new ArrayBuffer(bufferSize);
// Set `bufferSize` on open() to at least the size of the buffer.
await port.open({ baudRate: 9600, bufferSize });
const reader = port.readable.getReader({ mode: "byob" });
while (true) {
const { value, done } = await reader.read(new Uint8Array(buffer));
if (done) {
break;
}
buffer = value.buffer;
// Handle `value`.
}
Seri bağlantı noktasından belirli miktarda verinin nasıl okunacağına dair başka bir örnek aşağıda verilmiştir:
async function readInto(reader, buffer) {
let offset = 0;
while (offset < buffer.byteLength) {
const { value, done } = await reader.read(
new Uint8Array(buffer, offset)
);
if (done) {
break;
}
buffer = value.buffer;
offset += value.byteLength;
}
return buffer;
}
const reader = port.readable.getReader({ mode: "byob" });
let buffer = new ArrayBuffer(512);
// Read the first 512 bytes.
buffer = await readInto(reader, buffer);
// Then read the next 512 bytes.
buffer = await readInto(reader, buffer);
Seri bağlantı noktasına yazma
Seri cihaza veri göndermek için verileri port.writable.getWriter().write()
'e iletin. Seri bağlantı noktasının daha sonra kapatılması için port.writable.getWriter()
üzerinde releaseLock()
çağrısı yapılması gerekir.
const writer = port.writable.getWriter();
const data = new Uint8Array([104, 101, 108, 108, 111]); // hello
await writer.write(data);
// Allow the serial port to be closed later.
writer.releaseLock();
Metni, aşağıda gösterildiği gibi port.writable
hedefine bağlı bir TextEncoderStream
üzerinden cihaza gönderin.
const textEncoder = new TextEncoderStream();
const writableStreamClosed = textEncoder.readable.pipeTo(port.writable);
const writer = textEncoder.writable.getWriter();
await writer.write("hello");
Seri bağlantı noktasını kapatma
port.close()
, readable
ve writable
üyeleri kilidi açılmışsa seri bağlantı noktasını kapatır. Bu, ilgili okuyucu ve yazar için releaseLock()
çağrıldığı anlamına gelir.
await port.close();
Ancak bir döngü kullanarak seri cihazdan sürekli veri okurken port.readable
, bir hatayla karşılaşana kadar her zaman kilitli kalır. Bu durumda, reader.cancel()
çağrısı reader.read()
'u { value: undefined, done: true }
ile hemen çözmeye zorlar ve böylece döngünün reader.releaseLock()
'ı çağırmasına izin verir.
// Without transform streams.
let keepReading = true;
let reader;
async function readUntilClosed() {
while (port.readable && keepReading) {
reader = port.readable.getReader();
try {
while (true) {
const { value, done } = await reader.read();
if (done) {
// reader.cancel() has been called.
break;
}
// value is a Uint8Array.
console.log(value);
}
} catch (error) {
// Handle error...
} finally {
// Allow the serial port to be closed later.
reader.releaseLock();
}
}
await port.close();
}
const closedPromise = readUntilClosed();
document.querySelector('button').addEventListener('click', async () => {
// User clicked a button to close the serial port.
keepReading = false;
// Force reader.read() to resolve immediately and subsequently
// call reader.releaseLock() in the loop example above.
reader.cancel();
await closedPromise;
});
Dönüşüm akışları kullanılırken seri bağlantı noktasının kapatılması daha karmaşık bir işlemdir. reader.cancel()
'ü eskisi gibi arayın.
Ardından writer.close()
ve port.close()
'u arayın. Bu, dönüştürme akışları aracılığıyla hataları temel seri bağlantı noktasına iletir. Hata yayma işlemi hemen gerçekleşmediğinden, port.readable
ve port.writable
'in kilidinin ne zaman açıldığını algılamak için daha önce oluşturulan readableStreamClosed
ve writableStreamClosed
vaatlerini kullanmanız gerekir. reader
'ü iptal etmek aktarımın iptal edilmesine neden olur. Bu nedenle, ortaya çıkan hatayı yakalayıp yoksaymanız gerekir.
// With transform streams.
const textDecoder = new TextDecoderStream();
const readableStreamClosed = port.readable.pipeTo(textDecoder.writable);
const reader = textDecoder.readable.getReader();
// Listen to data coming from the serial device.
while (true) {
const { value, done } = await reader.read();
if (done) {
reader.releaseLock();
break;
}
// value is a string.
console.log(value);
}
const textEncoder = new TextEncoderStream();
const writableStreamClosed = textEncoder.readable.pipeTo(port.writable);
reader.cancel();
await readableStreamClosed.catch(() => { /* Ignore the error */ });
writer.close();
await writableStreamClosed;
await port.close();
Bağlantı ve bağlantı kesme seslerini dinleme
USB cihaz tarafından seri bağlantı noktası sağlanıyorsa söz konusu cihaz sistemle bağlı veya sistemden ayrılmış olabilir. Web sitesine seri bağlantı noktasına erişme izni verildiğinde connect
ve disconnect
etkinliklerini izlemelidir.
navigator.serial.addEventListener("connect", (event) => {
// TODO: Automatically open event.target or warn user a port is available.
});
navigator.serial.addEventListener("disconnect", (event) => {
// TODO: Remove |event.target| from the UI.
// If the serial port was opened, a stream error would be observed as well.
});
Sinyalleri işleme
Seri bağlantı noktası bağlantısını oluşturduktan sonra, cihaz algılama ve akış kontrolü için seri bağlantı noktası tarafından sunulan sinyalleri açıkça sorgulayabilir ve ayarlayabilirsiniz. Bu sinyaller, boole değerleri olarak tanımlanır. Örneğin, Arduino gibi bazı cihazlar Veri Terminali Hazır (DTR) sinyali etkinleştirildiğinde programlama moduna girer.
Çıkış sinyallerini ayarlama ve giriş sinyallerini alma işlemleri sırasıyla port.setSignals()
ve port.getSignals()
çağrılarak yapılır. Aşağıdaki kullanım örneklerini inceleyin.
// Turn off Serial Break signal.
await port.setSignals({ break: false });
// Turn on Data Terminal Ready (DTR) signal.
await port.setSignals({ dataTerminalReady: true });
// Turn off Request To Send (RTS) signal.
await port.setSignals({ requestToSend: false });
const signals = await port.getSignals();
console.log(`Clear To Send: ${signals.clearToSend}`);
console.log(`Data Carrier Detect: ${signals.dataCarrierDetect}`);
console.log(`Data Set Ready: ${signals.dataSetReady}`);
console.log(`Ring Indicator: ${signals.ringIndicator}`);
Akışları dönüştürme
Seri cihazdan veri aldığınızda tüm verileri bir kerede almayabilirsiniz. Rastgele parçalanabilir. Daha fazla bilgi için Streams API kavramları başlıklı makaleyi inceleyin.
Bu sorunu çözmek için TextDecoderStream
gibi bazı yerleşik dönüştürme akışlarını kullanabilir veya gelen akışı ayrıştırmanıza ve ayrıştırılan verileri döndürmenize olanak tanıyan kendi dönüştürme akışınızı oluşturabilirsiniz. Dönüşüm akışı, seri cihaz ile akışı tüketen okuma döngüsü arasında yer alır. Veriler kullanılmadan önce rastgele bir dönüştürme işlemi uygulayabilir. Bu süreci bir montaj hattı gibi düşünebilirsiniz: Bir widget hattan geçerken hattaki her adım widget'ı değiştirir. Böylece widget, son hedefine ulaştığında tamamen çalışır durumda olur.
Örneğin, bir akışı tüketen ve satır sonlarına göre parçalara ayıran bir dönüştürme akışı sınıfını nasıl oluşturacağınızı düşünün. Bu transform()
yöntemi, akış tarafından her yeni veri alındığında çağrılır. Verileri sıraya alabilir veya
daha sonra kullanmak üzere kaydedebilir. flush()
yöntemi, akış kapatıldığında çağrılır ve henüz işlenmemiş tüm verileri işler.
Dönüşüm akışı sınıfını kullanmak için gelen bir akışı bu sınıftan geçirmeniz gerekir. Seri bağlantı noktasından okuma bölümündeki üçüncü kod örneğinde, orijinal giriş akışı yalnızca bir TextDecoderStream
üzerinden aktarılmıştır. Bu nedenle, yeni LineBreakTransformer
'imiz üzerinden aktarmak için pipeThrough()
'ı çağırmamız gerekir.
class LineBreakTransformer {
constructor() {
// A container for holding stream data until a new line.
this.chunks = "";
}
transform(chunk, controller) {
// Append new chunks to existing chunks.
this.chunks += chunk;
// For each line breaks in chunks, send the parsed lines out.
const lines = this.chunks.split("\r\n");
this.chunks = lines.pop();
lines.forEach((line) => controller.enqueue(line));
}
flush(controller) {
// When the stream is closed, flush any remaining chunks out.
controller.enqueue(this.chunks);
}
}
const textDecoder = new TextDecoderStream();
const readableStreamClosed = port.readable.pipeTo(textDecoder.writable);
const reader = textDecoder.readable
.pipeThrough(new TransformStream(new LineBreakTransformer()))
.getReader();
Seri cihaz iletişim sorunlarını ayıklamak için seri cihaza gelen veya cihazdan giden akışları bölmek üzere port.readable
sınıfının tee()
yöntemini kullanın. Oluşturulan iki akış bağımsız olarak kullanılabilir. Bu sayede, inceleme için bir akışı konsola yazdırabilirsiniz.
const [appReadable, devReadable] = port.readable.tee();
// You may want to update UI with incoming data from appReadable
// and log incoming data in JS console for inspection from devReadable.
Seri bağlantı noktasına erişimi iptal etme
Web sitesi, SerialPort
örneğinde forget()
'yi çağırarak artık tutmaya istekli olmadığı bir seri bağlantı noktasına erişim izinlerini temizleyebilir. Örneğin, birçok cihazın bulunduğu paylaşılan bir bilgisayarda kullanılan eğitim amaçlı bir web uygulamasında, kullanıcı tarafından oluşturulan çok sayıda izin birikmesi kötü bir kullanıcı deneyimi oluşturur.
// Voluntarily revoke access to this serial port.
await port.forget();
forget()
, Chrome 103 veya sonraki sürümlerinde kullanıma sunulduğundan, bu özelliğin aşağıdakilerle desteklenip desteklenmediğini kontrol edin:
if ("serial" in navigator && "forget" in SerialPort.prototype) {
// forget() is supported.
}
Geliştirici İpuçları
Chrome'da Web Seri API'de hata ayıklama işlemi, seri cihazla ilgili tüm etkinlikleri tek bir yerde görebileceğiniz dahili sayfa about://device-log
ile kolaydır.
Codelab
Google Developer codelab'de, 5x5 LED matrisinde resim göstermek için BBC micro:bit kartıyla etkileşimde bulunmak üzere Web Seri API'yi kullanacaksınız.
Tarayıcı desteği
Web Serial API, Chrome 89'da tüm masaüstü platformlarında (ChromeOS, Linux, macOS ve Windows) kullanılabilir.
Çoklu Dolgu
Android'de, WebUSB API ve Serial API polyfill kullanılarak USB tabanlı seri bağlantı noktaları desteklenir. Bu çoklu dolgu, yerleşik bir cihaz sürücüsü tarafından üzerinde hak talebinde bulunulmadığından cihaza WebUSB API üzerinden erişilebildiği donanım ve platformlarla sınırlıdır.
Güvenlik ve gizlilik
Bu spesifikasyonların yazarları, Web Serial API'yi Güçlü Web Platformu Özelliklerine Erişimi Kontrol Etme konusunda tanımlanan temel ilkeleri (kullanıcı kontrolü, şeffaflık ve ergonomi dahil) kullanarak tasarlamış ve uygulamıştır. Bu API'nin kullanılabilmesi, temel olarak tek seferde yalnızca tek bir seri cihaza erişim izni veren bir izin modeliyle sınırlandırılmıştır. Kullanıcı istemine yanıt olarak, kullanıcının belirli bir seri cihazı seçmek için aktif adımlar atması gerekir.
Güvenliğin artılarını ve eksilerini anlamak için Web Serial API Explainer'ın güvenlik ve gizlilik bölümlerine göz atın.
Geri bildirim
Chrome ekibi, Web Seri API'si hakkındaki düşüncelerinizi ve deneyimlerinizi öğrenmekten memnuniyet duyar.
Bize API tasarımı hakkında bilgi verin
API ile ilgili beklendiği gibi çalışmayan bir şey var mı? Yoksa fikrinizi uygulamak için ihtiyaç duyduğunuz yöntemler veya özellikler eksik mi?
Web Serial API GitHub deposunda spesifikasyon sorunu bildirin veya mevcut bir soruna düşüncelerinizi ekleyin.
Uygulamayla ilgili bir sorunu bildirin
Chrome'un uygulamasında bir hata mı buldunuz? Yoksa uygulama, spesifikasyondan farklı mı?
https://new.crbug.com adresinden hata kaydı oluşturun. Mümkün olduğunca fazla ayrıntı eklediğinizden, hatayı yeniden oluşturmayla ilgili basit talimatlar sağladığınızdan ve Bileşenler'in Blink>Serial
olarak ayarlandığından emin olun. Glitch, hızlı ve kolay yeniden oluşturma işlemlerini paylaşmak için mükemmel bir araçtır.
Destek gösterme
Web Serial API'yi kullanmayı planlıyor musunuz? Herkese açık desteğiniz, Chrome ekibinin özellikleri önceliklendirmesine yardımcı olur ve diğer tarayıcı tedarikçilerine bunları desteklemenin ne kadar kritik olduğunu gösterir.
#SerialAPI
hashtag'ini kullanarak @ChromiumDev hesabına tweet gönderin ve bu özelliği nerede ve nasıl kullandığınızı bize bildirin.
Faydalı bağlantılar
- Özellik
- İzleme hatası
- ChromeStatus.com girişi
- Blink Bileşeni:
Blink>Serial
Demolar
Teşekkür
Bu makaleyi inceleyen Reilly Grant ve Joe Medley'e teşekkür ederiz. Birmingham Museums Trust'ın Unsplash'ta yer alan uçak fabrikası fotoğrafı.