diff options
Diffstat (limited to 'pw_web/docs.rst')
| -rw-r--r-- | pw_web/docs.rst | 156 |
1 files changed, 139 insertions, 17 deletions
diff --git a/pw_web/docs.rst b/pw_web/docs.rst index a6eddf98e..d90c22a6a 100644 --- a/pw_web/docs.rst +++ b/pw_web/docs.rst @@ -3,7 +3,6 @@ --------- pw_web --------- - Pigweed provides an NPM package with modules to build web apps for Pigweed devices. @@ -16,26 +15,25 @@ Installation ------------- If you have a bundler set up, you can install ``pigweedjs`` in your web application by: -.. code:: bash +.. code-block:: bash $ npm install --save pigweedjs After installing, you can import modules from ``pigweedjs`` in this way: -.. code:: javascript +.. code-block:: javascript import { pw_rpc, pw_tokenizer, Device, WebSerial } from 'pigweedjs'; Import Directly in HTML ^^^^^^^^^^^^^^^^^^^^^^^ - If you don't want to set up a bundler, you can also load Pigweed directly in your HTML page by: -.. code:: html +.. code-block:: html - <script src="https://unpkg.com/pigweedjs@0.0.5/dist/index.umd.js"></script> + <script src="https://unpkg.com/pigweedjs/dist/index.umd.js"></script> <script> const { pw_rpc, pw_hdlc, Device, WebSerial } from Pigweed; </script> @@ -50,15 +48,15 @@ instructions on how to build the demo and try things out. ``pigweedjs`` provides a ``Device`` API which simplifies common tasks. Here is an example to connect to device and call ``EchoService.Echo`` RPC service. -.. code:: html +.. code-block:: html <h1>Hello Pigweed</h1> <button onclick="connect()">Connect</button> <button onclick="echo()">Echo RPC</button> <br /><br /> <code></code> - <script src="https://unpkg.com/pigweedjs@0.0.5/dist/index.umd.js"></script> - <script src="https://unpkg.com/pigweedjs@0.0.5/dist/protos/collection.umd.js"></script> + <script src="https://unpkg.com/pigweedjs/dist/index.umd.js"></script> + <script src="https://unpkg.com/pigweedjs/dist/protos/collection.umd.js"></script> <script> const { Device } = Pigweed; const { ProtoCollection } = PigweedProtoCollection; @@ -79,14 +77,14 @@ pw_system demo uses ``pw_log_rpc``; an RPC-based logging solution. pw_system also uses pw_tokenizer to tokenize strings and save device space. Below is an example that streams logs using the ``Device`` API. -.. code:: html +.. code-block:: html <h1>Hello Pigweed</h1> <button onclick="connect()">Connect</button> <br /><br /> <code></code> - <script src="https://unpkg.com/pigweedjs@0.0.5/dist/index.umd.js"></script> - <script src="https://unpkg.com/pigweedjs@0.0.5/dist/protos/collection.umd.js"></script> + <script src="https://unpkg.com/pigweedjs/dist/index.umd.js"></script> + <script src="https://unpkg.com/pigweedjs/dist/protos/collection.umd.js"></script> <script> const { Device, pw_tokenizer } = Pigweed; const { ProtoCollection } = PigweedProtoCollection; @@ -110,7 +108,7 @@ example that streams logs using the ``Device`` API. The above example requires a token database in CSV format. You can generate one from the pw_system's ``.elf`` file by running: -.. code:: bash +.. code-block:: bash $ pw_tokenizer/py/pw_tokenizer/database.py create \ --database db.csv out/stm32f429i_disc1_stm32cube.size_optimized/obj/pw_system/bin/system_example.elf @@ -149,12 +147,11 @@ Device has following public API: WebSerialTransport ------------------ - To help with connecting to WebSerial and listening for serial data, a helper class is also included under ``WebSerial.WebSerialTransport``. Here is an example usage: -.. code:: javascript +.. code-block:: javascript import { WebSerial, pw_hdlc } from 'pigweedjs'; @@ -164,6 +161,9 @@ example usage: // Present device selection prompt to user await transport.connect(); + // Or connect to an existing `SerialPort` + // await transport.connectPort(port); + // Listen and decode HDLC frames transport.chunks.subscribe((item) => { const decoded = decoder.process(item); @@ -175,6 +175,8 @@ example usage: } }); + // Later, close all streams and close the port. + transport.disconnect(); Individual Modules ================== @@ -187,13 +189,133 @@ Following Pigweed modules are included in the NPM package: Web Console =========== - Pigweed includes a web console that demonstrates `pigweedjs` usage in a React-based web app. Web console includes a log viewer and a REPL that supports autocomplete. Here's how to run the web console locally: -.. code:: bash +.. code-block:: bash $ cd pw_web/webconsole $ npm install $ npm run dev + +Log viewer component +==================== +The NPM package also includes a log viewer component that can be embedded in any +webapp. The component works with Pigweed's RPC stack out-of-the-box but also +supports defining your own log source. + +The component is composed of the component itself and a log source. Here is a +simple example app that uses a mock log source: + +.. code-block:: html + + <div id="log-viewer-container"></div> + <script src="https://unpkg.com/pigweedjs/dist/logging.umd.js"></script> + <script> + + const { createLogViewer, MockLogSource } = PigweedLogging; + const logSource = new MockLogSource(); + const containerEl = document.querySelector( + '#log-viewer-container' + ); + + let unsubscribe = createLogViewer(logSource, containerEl); + logSource.start(); // Start producing mock logs + + </script> + +The code above will render a working log viewer that just streams mock +log entries. + +It also comes with an RPC log source with support for detokenization. Here is an +example app using that: + +.. code-block:: html + + <div id="log-viewer-container"></div> + <script src="https://unpkg.com/pigweedjs/dist/index.umd.js"></script> + <script src="https://unpkg.com/pigweedjs/dist/protos/collection.umd.js"></script> + <script src="https://unpkg.com/pigweedjs/dist/logging.umd.js"></script> + <script> + + const { Device, pw_tokenizer } = Pigweed; + const { ProtoCollection } = PigweedProtoCollection; + const { createLogViewer, PigweedRPCLogSource } = PigweedLogging; + + const device = new Device(new ProtoCollection()); + const logSource = new PigweedRPCLogSource(device, "CSV TOKEN DB HERE"); + const containerEl = document.querySelector( + '#log-viewer-container' + ); + + let unsubscribe = createLogViewer(logSource, containerEl); + + </script> + +Custom Log Source +----------------- +You can define a custom log source that works with the log viewer component by +just extending the abstract `LogSource` class and emitting the `logEntry` events +like this: + +.. code-block:: typescript + + import { LogSource, LogEntry, Severity } from 'pigweedjs/logging'; + + export class MockLogSource extends LogSource { + constructor(){ + super(); + // Do any initializations here + // ... + // Then emit logs + const log1: LogEntry = { + + } + this.emitEvent('logEntry', { + severity: Severity.INFO, + timestamp: new Date(), + fields: [ + { key: 'severity', value: severity } + { key: 'timestamp', value: new Date().toISOString() }, + { key: 'source', value: "LEFT SHOE" }, + { key: 'message', value: "Running mode activated." } + ] + }); + } + } + +After this, you just need to pass your custom log source object +to `createLogViewer()`. See implementation of +`PigweedRPCLogSource <https://cs.opensource.google/pigweed/pigweed/+/main:ts/logging_source_rpc.ts>`_ +for reference. + +Color Scheme +------------ +The log viewer web component provides the ability to set the color scheme manually, overriding any default or system preferences. + +To set the color scheme, first obtain a reference to the ``log-viewer`` element in the DOM. A common way to do this is by using ``querySelector()``: + +.. code-block:: javascript + + const logViewer = document.querySelector('log-viewer'); + +You can then set the color scheme dynamically by updating the component's `colorScheme` property or by setting a value for the `colorscheme` HTML attribute. + +.. code-block:: javascript + + logViewer.colorScheme = 'dark'; + +.. code-block:: javascript + + logViewer.setAttribute('colorscheme', 'dark'); + +The color scheme can be set to ``'dark'``, ``'light'``, or the default ``'auto'`` which allows the component to adapt to the preferences in the operating system settings. + +Guides +====== + +.. toctree:: + :maxdepth: 1 + + testing |