|
| 1 | + |
| 2 | +# WSC SDK |
| 3 | +A JavaScript implementation of the [WSC](https://github.com/ASLS-org/WSC) wire format that is independent of any I/O or transport layer, exposing the protocol through idiomatic types, functions, and constants without prescribing how packets are sent or received. |
| 4 | + |
| 5 | +>**About WSC:**<br> |
| 6 | +[WSC](https://github.com/ASLS-org/WSC) defines a unified wire format that transports DMX data, linear timecode, cue triggers, structured parameter updates, and arbitrary binary payloads. A gateway can then relay this data to downstream protocols such as Art-Net, sACN, OSC, MIDI, Modbus, and others. |
| 7 | +## Public API |
| 8 | + |
| 9 | +All domain constants live as static members of their owning class: |
| 10 | + |
| 11 | +| Class | Responsibility | |
| 12 | +|---|---| |
| 13 | +| `WscPacket` | Packet construction, serialization, deserialization, payload codecs, validation | |
| 14 | +| `WscTransport` | Transport Descriptor construction, serialization, compatibility matrices | |
| 15 | +| `WscAddress` | Address token encoding, dot-notation parsing, serialization | |
| 16 | +| `WscFlags` | Flags field serialization and validation | |
| 17 | +| `WscError` | Typed protocol error with class and error code | |
| 18 | +| `BinaryReader` / `BinaryWriter` | Low-level byte-level read/write helpers | |
| 19 | + |
| 20 | +## Constants |
| 21 | + |
| 22 | +| Expression | Values | |
| 23 | +|---|---| |
| 24 | +| `WscPacket.Type` | `STREAM_CHANNELS`, `STREAM_TIMECODE`, `CONTROL_CUE`, `CONTROL_PARAM`, `TUNNEL_RAW`, `STATE_QUERY`, `STATE_ANSWER`, `STATE_ERROR` | |
| 25 | +| `WscPacket.CueAction` | `LOAD`, `START`, `STOP`, `PAUSE`, `RESUME`, `RELEASE` | |
| 26 | +| `WscPacket.ValueType` | `U8`, `U16`, `U32`, `U64`, `I8`, `I16`, `I32`, `I64`, `F32`, `F64`, `STRING`, `BOOL` | |
| 27 | +| `WscPacket.StateQuery` | `KEEPALIVE` | |
| 28 | +| `WscPacket.Status` | `SUCCESS`, `PARTIAL`, `ERROR`, `NOT_FOUND`, `NOT_SUPPORTED`, `BUSY` | |
| 29 | +| `WscPacket.ErrorCode` | `PROTOCOL_VERSION` … `CONFIG_ERROR` | |
| 30 | +| `WscTransport.Protocol` | `DMX512`, `ARTNET`, `SACN`, `OSC`, `MIDI`, `MODBUS`, `RAW`, … | |
| 31 | +| `WscTransport.Iface` | `UDP`, `TCP`, `SERIAL`, `USB`, `WEBSOCKET`, `HTTP` | |
| 32 | +| `WscTransport.Addr` | `NONE`, `IPV4`, `IPV6`, `SERIAL`, `USB`, `HOSTNAME`, `URL` | |
| 33 | +| `WscTransport.Param` | `PRIORITY`, `TTL`, `BAUD_RATE`, `SEQUENCE`, `IFACE_IDX` | |
| 34 | +| `WscFlags.Bit` | `TR`, `GW`, `ACK`, `MC`, `TS` | |
| 35 | + |
| 36 | +## Packet factory |
| 37 | + |
| 38 | +```js |
| 39 | +// Construct a typed packet |
| 40 | +WscPacket.create(type, data, opts?) |
| 41 | +// opts: { id?, flags?: WscFlags, transport?: WscTransport } |
| 42 | + |
| 43 | +// Serialize |
| 44 | +packet.serialize() // → Uint8Array |
| 45 | + |
| 46 | +// Deserialize |
| 47 | +WscPacket.deserialize(buffer) // → WscPacket |
| 48 | + |
| 49 | +// Decode payload |
| 50 | +WscPacket.decode(packet) // → plain object | null |
| 51 | + |
| 52 | +// Validate before send |
| 53 | +WscPacket.validate(packet) // → { valid, errors[], warnings[] } |
| 54 | +``` |
| 55 | +
|
| 56 | +## Transport factory methods |
| 57 | +
|
| 58 | +```js |
| 59 | +WscTransport.udp(protocol, ip, port) |
| 60 | +WscTransport.tcp(protocol, ip, port) |
| 61 | +WscTransport.serial(protocol, portIndex, baudRate) |
| 62 | +WscTransport.usb(protocol, vendorId, productId) |
| 63 | +WscTransport.http(protocol, url) |
| 64 | +WscTransport.websocket(protocol, url) |
| 65 | +WscTransport.raw() |
| 66 | +``` |
| 67 | +
|
| 68 | +## Address parsing |
| 69 | +
|
| 70 | +```js |
| 71 | +// From dot-notation string |
| 72 | +WscAddress.parse('lighting.layer.2.intensity') // → WscAddress |
| 73 | + |
| 74 | +// From token array |
| 75 | +WscAddress.build([WscToken.AUDIO, WscToken.TRACK, 3, WscToken.LEVEL]) |
| 76 | + |
| 77 | +// Round-trip |
| 78 | +addr.serialize() // → Uint8Array |
| 79 | +WscAddress.deserialize(bytes) // → WscAddress |
| 80 | +addr.toString() // → 'lighting.layer.2.intensity' |
| 81 | +``` |
0 commit comments