diff --git a/docs/index.md b/docs/index.md index 3ba7589d..6b53a0e2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -25,6 +25,7 @@ If that's no problem you can head over to the [installation guide](./getting_sta - AutoHotkey - Android (using adb) +- ArtNet - CurseForge - DBus - Discord diff --git a/docs/samples/artnet.md b/docs/samples/artnet.md new file mode 100644 index 00000000..6a78ca7e --- /dev/null +++ b/docs/samples/artnet.md @@ -0,0 +1,95 @@ +## Using the Art-Net sample bundle + +The Art-Net example bundle in `samples/artnet-console` demonstrates the ability send data via Art-Net to e.g., open lighting architecture or professional lighting equipment. Here is a guide to how to get it working. The underlying service is using [`jeffreykog/node-artnet-protocol`](https://github.com/jeffreykog/node-artnet-protocol) as its library. + +### Prerequisites + +- Working NodeCG & nodecg-io installation +- A working Art-Net Node in the current network + +### Configure the Art-Net sample bundle + +1. Start nodecg with nodecg-io installed. The artnet-console sample bundle is currently part of it, so it should also be loaded. + +2. Go to the `nodecg-io` tab in the nodecg dashboard. + +3. Login using your password. If this is your first run, then enter the password with which you want to encrypt your configurations and credentials. + +4. Create a new artnet service instance using the left upper menu. + +5. Enter the needed option. + + The created instance should be automatically selected, if not select it in the upper left dropdown. Enter your universe in monaco (the text-editor on the right) in this format: + + **Host** + + The broadcast address the Art-Net library will use to send `dmx` packages. + + ```json + { + "host": "127.0.0.1" + } + ``` + + After entering it, click save. + + You may overwrite this broadcast address in code with `client.bind("host address");`. + + _Note:_ If you don't see monaco on the right, try reloading the page. + +6. Set the created artnet service instance to the service dependency of the artnet-console bundle. + + Select the artnet-console bundle and the artnet service in the left bottom dropdown and then select the service instance that should be used by the artnet-console bundle (in this case the name of the previously created artnet instance). + +7. Check the nodecg logs + + You should see data logged. + +### Explanations + +#### Receiving DMX data + +```ts +client.onDMX((dmx) => { + // dmx contains an ArtDmx object + nodecg.log.info(dmx.universe, dmx.data); +}); +``` + +The data you receive has the following fields: + +```ts +declare class ArtDmx { + opcode: number; + protocolVersion: number; + sequence: number; + physical: number; + universe: number; + data: number[]; + constructor(sequence: number, physical: number, universe: number, data: number[]); + isSequenceEnabled(): boolean; + static decode(data: Buffer): ArtDmx; + toString(): string; + encode(): Buffer; +} +``` + +#### Sending DMX data + +```ts +// send new data every 0,8 seconds. +// This is the official timing for re-transmiting data in the artnet specifciation. +setInterval(() => { + client.send(universe, + values // number[] of values for each of the 512 channels + ); +}, 800); +``` + +_Note_: Since neither this library nor nodecg-io does not yet contain an abstraction, so the data is sent to the timings set by the specification, you should respect this part of specification in **your implementation**. + +> However, an input that is active but not changing, will re-transmit the last valid ArtDmx +> packet at approximately 4-second intervals. (_Note_. In order to converge the needs of Art- +> Net and sACN it is recommended that Art-Net devices actually use a re-transmit time of +> 800mS to 1000mS). +> — [Art-Net 4 Specification p. 48](https://artisticlicence.com/WebSiteMaster/User%20Guides/art-net.pdf) diff --git a/docs/samples/sacn-receiver.md b/docs/samples/sacn-receiver.md index a422fc5e..e32bdab2 100644 --- a/docs/samples/sacn-receiver.md +++ b/docs/samples/sacn-receiver.md @@ -7,7 +7,7 @@ The sacn-receiver-sample example bundle in `samples/sacn-receiver-sample` demons - Working NodeCG & nodecg-io installation - A working sACN sender in the current network -### Configure the Discord sample bundle +### Configure the sACN sample bundle 1. Start nodecg with nodecg-io installed. The sacn-receiver-sample bundle is currently part of it so it should also be loaded. diff --git a/docs/samples/sacn-sender.md b/docs/samples/sacn-sender.md index f9fb4c1e..3112cf1a 100644 --- a/docs/samples/sacn-sender.md +++ b/docs/samples/sacn-sender.md @@ -7,7 +7,7 @@ The sacn-sender example bundle in `samples/sacn-sender` demonstrates the ability - Working NodeCG & nodecg-io installation - A working sACN receiver in the current network -### Configure the Discord sample bundle +### Configure the sACN sample bundle 1. Start nodecg with nodecg-io installed. The sacn-receiver-sample bundle is currently part of it so it should also be loaded. diff --git a/mkdocs.yml b/mkdocs.yml index 6334b2c6..93edcb1a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -50,13 +50,14 @@ nav: - Services: - Available services: services.md - AHK sample: samples/ahk.md + - Art-Net sample: samples/artnet.md - Curseforge sample: samples/curseforge.md - Android: samples/android.md - Debug: samples/debug.md - Discord sample: samples/discord.md - GitHub sample: samples/github.md - Googleapis: - - GSheets sample: samples/ghseets.md + - GSheets sample: samples/ghseets.md - Youtube sample: samples/youtube.md - IntelliJ sample: samples/intellij.md - IRC: samples/irc.md @@ -98,7 +99,7 @@ extra_css: extra: version: - provider: mike + provider: mike social: - icon: fontawesome/brands/discord link: https://discord.gg/sX2Gjbs