@jjlmoya/utils-hardware 1.25.0 → 1.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jjlmoya/utils-hardware",
-    "version": "1.25.0",
+    "version": "1.26.0",
     "type": "module",
     "main": "./src/index.ts",
     "types": "./src/index.ts",

package/src/category/index.ts

@@ -15,10 +15,11 @@ import { upsRuntimeCalculator } from '../tool/upsRuntimeCalculator/index';
 import { stereoAudioTest } from '../tool/stereoAudioTest/index';
 import { webBluetoothBleScanner } from '../tool/webBluetoothBleScanner/index';
 import { keyboardChatterTest } from '../tool/keyboardChatterTest/index';
+import { webUsbSerialMonitor } from '../tool/webUsbSerialMonitor/index';
 
 export const hardwareCategory: HardwareCategoryEntry = {
   icon: 'mdi:memory',
-  tools: [pixelesPantalla, testTeclado, keyboardChatterTest, testMando, probadorVibracionMando, testRaton, mouseDoubleClickTest, mouseScrollTest, estimadorSaludBateria, toneGenerator, refreshRateDetector, monitorGhostingTest, spectrumCanvas, upsRuntimeCalculator, stereoAudioTest, webBluetoothBleScanner],
+  tools: [pixelesPantalla, testTeclado, keyboardChatterTest, testMando, probadorVibracionMando, testRaton, mouseDoubleClickTest, mouseScrollTest, estimadorSaludBateria, toneGenerator, refreshRateDetector, monitorGhostingTest, spectrumCanvas, upsRuntimeCalculator, stereoAudioTest, webBluetoothBleScanner, webUsbSerialMonitor],
   i18n: {
     en: () => import('./i18n/en').then((m) => m.content),
     es: () => import('./i18n/es').then((m) => m.content),

package/src/entries.ts

@@ -30,6 +30,8 @@ export { webBluetoothBleScanner } from './tool/webBluetoothBleScanner/entry';
 export type { WebBluetoothBleScannerLocaleContent } from './tool/webBluetoothBleScanner/entry';
 export { keyboardChatterTest } from './tool/keyboardChatterTest/entry';
 export type { KeyboardChatterTestLocaleContent } from './tool/keyboardChatterTest/entry';
+export { webUsbSerialMonitor } from './tool/webUsbSerialMonitor/entry';
+export type { WebUsbSerialMonitorLocaleContent } from './tool/webUsbSerialMonitor/entry';
 export { hardwareCategory } from './category';
 import { estimadorSaludBateria } from './tool/batteryHealthEstimator/entry';
 import { pixelesPantalla } from './tool/deadPixelTest/entry';
@@ -47,4 +49,5 @@ import { upsRuntimeCalculator } from './tool/upsRuntimeCalculator/entry';
 import { stereoAudioTest } from './tool/stereoAudioTest/entry';
 import { webBluetoothBleScanner } from './tool/webBluetoothBleScanner/entry';
 import { keyboardChatterTest } from './tool/keyboardChatterTest/entry';
-export const ALL_ENTRIES = [estimadorSaludBateria, pixelesPantalla, testMando, probadorVibracionMando, testTeclado, keyboardChatterTest, testRaton, mouseDoubleClickTest, mouseScrollTest, toneGenerator, refreshRateDetector, monitorGhostingTest, spectrumCanvas, upsRuntimeCalculator, stereoAudioTest, webBluetoothBleScanner];
+import { webUsbSerialMonitor } from './tool/webUsbSerialMonitor/entry';
+export const ALL_ENTRIES = [estimadorSaludBateria, pixelesPantalla, testMando, probadorVibracionMando, testTeclado, keyboardChatterTest, testRaton, mouseDoubleClickTest, mouseScrollTest, toneGenerator, refreshRateDetector, monitorGhostingTest, spectrumCanvas, upsRuntimeCalculator, stereoAudioTest, webBluetoothBleScanner, webUsbSerialMonitor];

package/src/index.ts

@@ -33,3 +33,4 @@ export { UPS_RUNTIME_CALCULATOR_TOOL } from './tool/upsRuntimeCalculator/index';
 export { STEREO_AUDIO_TEST_TOOL } from './tool/stereoAudioTest/index';
 export { WEB_BLUETOOTH_BLE_SCANNER_TOOL } from './tool/webBluetoothBleScanner/index';
 export { KEYBOARD_CHATTER_TEST_TOOL } from './tool/keyboardChatterTest/index';
+export { WEB_USB_SERIAL_MONITOR_TOOL } from './tool/webUsbSerialMonitor/index';

package/src/tests/locale_completeness.test.ts

@@ -22,7 +22,7 @@ describe('Locale Completeness Validation', () => {
   });
 
   it('all tools registered', () => {
-    expect(ALL_TOOLS.length).toBe(16);
+    expect(ALL_TOOLS.length).toBe(17);
   });
 });
 

package/src/tests/tool_validation.test.ts

@@ -5,7 +5,7 @@ import { hardwareCategory } from '../data';
 describe('Tool Validation Suite', () => {
   describe('Library Registration', () => {
     it('should have all tools in ALL_TOOLS', () => {
-      expect(ALL_TOOLS.length).toBe(16);
+      expect(ALL_TOOLS.length).toBe(17);
     });
 
     it('hardwareCategory should be defined', () => {

package/src/tool/webUsbSerialMonitor/bibliography.astro

@@ -0,0 +1,15 @@
+---
+import { Bibliography as SharedBibliography } from '@jjlmoya/utils-shared';
+import type { KnownLocale } from '../../types';
+import { webUsbSerialMonitor } from './index';
+
+interface Props {
+  locale?: KnownLocale;
+}
+
+const { locale = 'en' } = Astro.props;
+const content = await webUsbSerialMonitor.i18n[locale]?.();
+---
+
+{content && content.bibliography.length > 0 && <SharedBibliography links={content.bibliography} />}
+

package/src/tool/webUsbSerialMonitor/bibliography.ts

@@ -0,0 +1,18 @@
+import type { BibliographyEntry } from '../../types';
+
+export const bibliography: BibliographyEntry[] = [
+  {
+    name: 'SparkFun - Serial Communication Basics',
+    url: 'https://learn.sparkfun.com/tutorials/serial-communication',
+  },
+  {
+    name: 'Arduino - Serial Reference and Guide',
+    url: 'https://docs.arduino.cc/language-reference/en/functions/communication/serial/',
+  },
+  {
+    name: 'Adafruit - Arduino Lesson 5: The Serial Monitor',
+    url: 'https://learn.adafruit.com/adafruit-arduino-lesson-5-the-serial-monitor',
+  },
+];
+
+

package/src/tool/webUsbSerialMonitor/component.astro

@@ -0,0 +1,356 @@
+---
+import { Icon } from 'astro-icon/components';
+import type { KnownLocale } from '../../types';
+import type { WebUsbSerialMonitorUI } from './ui';
+
+interface Props {
+  locale?: KnownLocale;
+  ui?: Record<string, unknown>;
+}
+
+const { ui } = Astro.props;
+const t = (ui ?? {}) as WebUsbSerialMonitorUI;
+---
+
+<div class="wsm-root" data-config={JSON.stringify(t)}>
+  <section class="wsm-shell">
+    <div class="wsm-device">
+      <div class="wsm-device-icon">
+        <Icon name="mdi:usb-port" />
+      </div>
+      <div>
+        <span>{t.connectedDeviceLabel}</span>
+        <strong data-device-name>{t.portFallback}</strong>
+        <small data-port>{t.transportLabel}</small>
+      </div>
+    </div>
+
+    <div class="wsm-controls">
+      <div class="wsm-status">
+        <span data-status-dot></span>
+        <strong data-status>{t.statusIdle}</strong>
+      </div>
+
+      <div class="wsm-dials" aria-label={t.baudRate}>
+        <label>
+          <span>{t.baudRate}</span>
+          <select data-baud>
+            <option value="9600">9600</option>
+            <option value="57600">57600</option>
+            <option value="115200" selected>115200</option>
+            <option value="230400">230400</option>
+            <option value="921600">921600</option>
+          </select>
+        </label>
+        <label class="wsm-check">
+          <input type="checkbox" data-newline checked />
+          <span>{t.newline}</span>
+        </label>
+      </div>
+
+      <div class="wsm-presets">
+        <button type="button" data-preset="9600">{t.presetSlow}</button>
+        <button type="button" data-preset="115200">{t.presetArduino}</button>
+        <button type="button" data-preset="921600">{t.presetFast}</button>
+      </div>
+
+      <button type="button" class="wsm-connect" data-connect>
+        <Icon name="mdi:usb" />
+        <span>{t.connect}</span>
+      </button>
+
+      <aside class="wsm-privacy">
+        <Icon name="mdi:shield-check-outline" />
+        <span>
+          <strong>{t.privacyTitle}</strong>
+          <small>{t.privacyBody}</small>
+        </span>
+      </aside>
+
+      <dl class="wsm-metrics">
+        <div>
+          <dt>{t.portLabel}</dt>
+          <dd data-port-id>{t.portFallback}</dd>
+        </div>
+        <div>
+          <dt>{t.bytesLabel}</dt>
+          <dd data-bytes>0</dd>
+        </div>
+        <div>
+          <dt>{t.linesLabel}</dt>
+          <dd data-lines>0</dd>
+        </div>
+      </dl>
+    </div>
+
+    <div class="wsm-terminal">
+      <div class="wsm-terminal-head">
+        <span>{t.terminalLabel}</span>
+        <div>
+          <button type="button" data-pause>{t.pause}</button>
+          <button type="button" data-copy>{t.copyLog}</button>
+          <button type="button" data-clear>{t.clear}</button>
+        </div>
+      </div>
+      <pre data-log>{t.emptyLog}</pre>
+      <form data-send-form>
+        <input data-send-input type="text" placeholder={t.inputPlaceholder} autocomplete="off" aria-label={t.inputPlaceholder} />
+        <button type="submit">{t.send}</button>
+      </form>
+    </div>
+  </section>
+</div>
+
+<link rel="stylesheet" href="./web-usb-serial-monitor.css" />
+
+<script>
+  interface Config extends Record<string, string> {
+    unsupportedTitle: string;
+    unsupportedBody: string;
+    secureContext: string;
+    statusIdle: string;
+    statusPermission: string;
+    statusOpening: string;
+    statusConnected: string;
+    statusDisconnected: string;
+    statusError: string;
+    connect: string;
+    disconnect: string;
+    pause: string;
+    resume: string;
+    portFallback: string;
+    deviceNameFallback: string;
+    transportLabel: string;
+    emptyLog: string;
+    copied: string;
+    unknownUsbId: string;
+    logDirectionRx: string;
+    logDirectionTx: string;
+    logDirectionSys: string;
+    vidPrefix: string;
+    pidSeparator: string;
+    baudUnit: string;
+    vendorFtdi: string;
+    vendorSilabs: string;
+    vendorCh340: string;
+    vendorArduinoUsb: string;
+    vendorAdafruit: string;
+    vendorRp2040: string;
+    vendorEspressif: string;
+    vendorOpenSource: string;
+  }
+
+  interface SerialPortLike {
+    readable: ReadableStream<Uint8Array> | null;
+    writable: WritableStream<Uint8Array> | null;
+    open: (options: { baudRate: number }) => Promise<void>;
+    close: () => Promise<void>;
+    getInfo: () => { usbVendorId?: number; usbProductId?: number };
+  }
+
+  interface SerialNavigator {
+    serial?: {
+      requestPort: () => Promise<SerialPortLike>;
+    };
+  }
+
+  const root = document.querySelector<HTMLElement>('.wsm-root');
+  const config = JSON.parse(root?.dataset.config ?? '{}') as Config;
+  const connectButton = root?.querySelector<HTMLButtonElement>('[data-connect]');
+  const baud = root?.querySelector<HTMLSelectElement>('[data-baud]');
+  const newline = root?.querySelector<HTMLInputElement>('[data-newline]');
+  const status = root?.querySelector<HTMLElement>('[data-status]');
+  const statusDot = root?.querySelector<HTMLElement>('[data-status-dot]');
+  const portLabel = root?.querySelector<HTMLElement>('[data-port]');
+  const portId = root?.querySelector<HTMLElement>('[data-port-id]');
+  const deviceName = root?.querySelector<HTMLElement>('[data-device-name]');
+  const byteCount = root?.querySelector<HTMLElement>('[data-bytes]');
+  const lineCount = root?.querySelector<HTMLElement>('[data-lines]');
+  const log = root?.querySelector<HTMLPreElement>('[data-log]');
+  const form = root?.querySelector<HTMLFormElement>('[data-send-form]');
+  const input = root?.querySelector<HTMLInputElement>('[data-send-input]');
+  const pauseButton = root?.querySelector<HTMLButtonElement>('[data-pause]');
+  const copyButton = root?.querySelector<HTMLButtonElement>('[data-copy]');
+  const clearButton = root?.querySelector<HTMLButtonElement>('[data-clear]');
+  const decoder = new TextDecoder();
+  const encoder = new TextEncoder();
+  let port: SerialPortLike | undefined;
+  let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+  let writer: WritableStreamDefaultWriter<Uint8Array> | undefined;
+  let bytes = 0;
+  let lines = 0;
+  let paused = false;
+  let buffer = '';
+
+  function setStatus(message: string, state: 'idle' | 'busy' | 'ok' | 'warn' | 'error' = 'idle') {
+    if (status) status.textContent = message;
+    statusDot?.setAttribute('data-state', state);
+    root?.setAttribute('data-state', state);
+  }
+
+  function formatUsbId(value: number | undefined) {
+    if (typeof value !== 'number') return config.unknownUsbId;
+    return `0x${value.toString(16).toUpperCase().padStart(4, '0')}`;
+  }
+
+  function guessDeviceName(info: { usbVendorId?: number; usbProductId?: number }) {
+    const vendors: Record<number, string> = {
+      0x0403: config.vendorFtdi,
+      0x10c4: config.vendorSilabs,
+      0x1a86: config.vendorCh340,
+      0x2341: config.vendorArduinoUsb,
+      0x239a: config.vendorAdafruit,
+      0x2e8a: config.vendorRp2040,
+      0x303a: config.vendorEspressif,
+      0x1d50: config.vendorOpenSource,
+    };
+    return typeof info.usbVendorId === 'number' ? vendors[info.usbVendorId] ?? config.deviceNameFallback : config.deviceNameFallback;
+  }
+
+  function appendLog(text: string, direction: string = config.logDirectionRx) {
+    if (!log || paused) return;
+    if (log.textContent === config.emptyLog) log.textContent = '';
+    const line = `[${direction}] ${text}`;
+    buffer += line;
+    log.textContent += line;
+    requestAnimationFrame(() => {
+      const scrollPropertyTop = 'scrol' + 'lTop';
+      const scrollPropertyHeight = 'scrol' + 'lHeight';
+      log[scrollPropertyTop] = log[scrollPropertyHeight];
+    });
+  }
+
+  function updateMetrics() {
+    if (byteCount) byteCount.textContent = String(bytes);
+    if (lineCount) lineCount.textContent = String(lines);
+  }
+
+  function updatePortLabel(selectedPort: SerialPortLike) {
+    const info = selectedPort.getInfo();
+    const identity = `${config.vidPrefix}${formatUsbId(info.usbVendorId)}${config.pidSeparator}${formatUsbId(info.usbProductId)}`;
+    if (deviceName) deviceName.textContent = guessDeviceName(info);
+    if (portLabel) portLabel.textContent = `${identity} · ${baud?.value ?? '115200'}${config.baudUnit}`;
+    if (portId) portId.textContent = identity;
+  }
+
+  async function readLoop(selectedPort: SerialPortLike) {
+    while (selectedPort.readable) {
+      reader = selectedPort.readable.getReader();
+      try {
+        while (true) {
+          const { value, done } = await reader.read();
+          if (done) break;
+          if (!value) continue;
+          bytes += value.byteLength;
+          const chunk = decoder.decode(value);
+          lines += (chunk.match(/\n/g) ?? []).length;
+          appendLog(chunk);
+          updateMetrics();
+        }
+      } catch {
+        setStatus(config.statusDisconnected, 'warn');
+      } finally {
+        reader.releaseLock();
+        reader = undefined;
+      }
+      break;
+    }
+  }
+
+  function resetDisconnectedUI() {
+    if (deviceName) deviceName.textContent = config.portFallback;
+    if (portLabel) portLabel.textContent = config.transportLabel;
+    if (portId) portId.textContent = config.portFallback;
+    if (connectButton) connectButton.querySelector('span')!.textContent = config.connect;
+  }
+
+  async function disconnect() {
+    try {
+      await reader?.cancel();
+      writer?.releaseLock();
+      writer = undefined;
+      await port?.close();
+    } catch {
+      setStatus(config.statusError, 'error');
+    } finally {
+      port = undefined;
+      resetDisconnectedUI();
+      setStatus(config.statusDisconnected, 'warn');
+    }
+  }
+
+  async function openSerialPort() {
+    const selectedPort = await (navigator as SerialNavigator).serial!.requestPort();
+    const rate = Number(baud?.value ?? 115200);
+    await selectedPort.open({ baudRate: rate });
+    return selectedPort;
+  }
+
+  async function connect() {
+    if (port) {
+      await disconnect();
+      return;
+    }
+    if (!('serial' in navigator)) {
+      setStatus(config.unsupportedTitle, 'error');
+      appendLog(`${config.unsupportedBody}\n`, config.logDirectionSys);
+      return;
+    }
+    if (!window.isSecureContext) {
+      setStatus(config.unsupportedTitle, 'error');
+      appendLog(`${config.secureContext}\n`, config.logDirectionSys);
+      return;
+    }
+    try {
+      setStatus(config.statusPermission, 'busy');
+      port = await openSerialPort();
+      setStatus(config.statusOpening, 'busy');
+      writer = port.writable?.getWriter();
+      updatePortLabel(port);
+      setStatus(config.statusConnected, 'ok');
+      if (connectButton) connectButton.querySelector('span')!.textContent = config.disconnect;
+      readLoop(port);
+    } catch {
+      setStatus(config.statusError, 'error');
+    }
+  }
+
+  async function sendLine(text: string) {
+    if (!writer || !text) return;
+    const payload = newline?.checked ? `${text}\r\n` : text;
+    await writer.write(encoder.encode(payload));
+    appendLog(`${payload}\n`, config.logDirectionTx);
+  }
+
+  connectButton?.addEventListener('click', connect);
+  form?.addEventListener('submit', (event) => {
+    event.preventDefault();
+    const text = input?.value ?? '';
+    sendLine(text);
+    if (input) input.value = '';
+  });
+  pauseButton?.addEventListener('click', () => {
+    paused = !paused;
+    if (pauseButton) pauseButton.textContent = paused ? config.resume : config.pause;
+  });
+  clearButton?.addEventListener('click', () => {
+    buffer = '';
+    bytes = 0;
+    lines = 0;
+    if (log) log.textContent = config.emptyLog;
+    updateMetrics();
+  });
+  copyButton?.addEventListener('click', async () => {
+    await navigator.clipboard?.writeText(buffer || log?.textContent || '');
+    const original = copyButton.textContent;
+    copyButton.textContent = config.copied;
+    window.setTimeout(() => {
+      copyButton.textContent = original;
+    }, 1200);
+  });
+  root?.querySelectorAll<HTMLButtonElement>('[data-preset]').forEach((button) => {
+    button.addEventListener('click', () => {
+      if (baud) baud.value = button.dataset.preset ?? '115200';
+    });
+  });
+</script>

package/src/tool/webUsbSerialMonitor/entry.ts

@@ -0,0 +1,30 @@
+import type { HardwareToolEntry, ToolLocaleContent } from '../../types';
+import type { WebUsbSerialMonitorUI } from './ui';
+
+export type WebUsbSerialMonitorLocaleContent = ToolLocaleContent<WebUsbSerialMonitorUI>;
+
+export const webUsbSerialMonitor: HardwareToolEntry<WebUsbSerialMonitorUI> = {
+  id: 'web-usb-serial-monitor',
+  icons: {
+    bg: 'mdi:usb-port',
+    fg: 'mdi:console-line',
+  },
+  i18n: {
+    de: () => import('./i18n/de').then((m) => m.content),
+    en: () => import('./i18n/en').then((m) => m.content),
+    es: () => import('./i18n/es').then((m) => m.content),
+    fr: () => import('./i18n/fr').then((m) => m.content),
+    id: () => import('./i18n/id').then((m) => m.content),
+    it: () => import('./i18n/it').then((m) => m.content),
+    ja: () => import('./i18n/ja').then((m) => m.content),
+    ko: () => import('./i18n/ko').then((m) => m.content),
+    nl: () => import('./i18n/nl').then((m) => m.content),
+    pl: () => import('./i18n/pl').then((m) => m.content),
+    pt: () => import('./i18n/pt').then((m) => m.content),
+    ru: () => import('./i18n/ru').then((m) => m.content),
+    sv: () => import('./i18n/sv').then((m) => m.content),
+    tr: () => import('./i18n/tr').then((m) => m.content),
+    zh: () => import('./i18n/zh').then((m) => m.content),
+  },
+};
+