From 8c365a268db3154efe0276f5be2478d6f705aac0 Mon Sep 17 00:00:00 2001 From: Tim_Tech_Dev Date: Mon, 11 Oct 2021 21:01:46 +0200 Subject: [PATCH 1/3] Implement an Art-Net service into nodecg-io - Add sample/artnet.md - Update mkdocs.yml - Update index.md - Fix little error in sACN samples --- docs/index.md | 1 + docs/samples/artnet.md | 123 ++++++++++++++++++++++++++++++++++ docs/samples/sacn-receiver.md | 2 +- docs/samples/sacn-sender.md | 2 +- mkdocs.yml | 5 +- 5 files changed, 129 insertions(+), 4 deletions(-) create mode 100644 docs/samples/artnet.md 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..c16984c2 --- /dev/null +++ b/docs/samples/artnet.md @@ -0,0 +1,123 @@ +## 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 + +**Contents of `./samples/artnet-console/extension/index.ts`** + +```ts +import { NodeCG } from "nodecg/types/server"; +import { requireService } from "nodecg-io-core"; +import { ArtNetServiceClient } from "nodecg-io-artnet"; + +module.exports = function (nodecg: NodeCG) { + nodecg.log.info("Sample bundle for Art-Net started"); + + const service = requireService(nodecg, "artnet"); + service?.onAvailable((client) => { + // From this point on is the artnet client available + nodecg.log.info("Art-Net console has been updated, setting up interval for sending test payloads."); + + // Receive DMX data + client.onDMX((dmx) => { + // dmx contains an ArtDmx object + nodecg.log.info(dmx.universe, dmx.data); + }); + + // Send DMX data to every channel and universe. + let value = 0; + setInterval(() => { + // send new data every 0,8 seconds. + // This is the official timing for re-transmiting data in the artnet specifciation. + if (++value > 255) value = 0; + for (let universe = 0; universe < 8; universe++) { + client.send( + universe, + // the values of the 512 channels + Array(512).fill(value) + ); + } + }, 800); + }); + + service?.onUnavailable(() => nodecg.log.info("Art-Net console has been unset.")); +}; +``` + +#### Receiving 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 + +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) + +``` +Test +``` 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..a6b48893 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -50,13 +50,14 @@ nav: - Services: - Available services: services.md - AHK sample: samples/ahk.md + - Atr-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 From 4ec7fd9a4985158b10da1b829976ba36de9117ae Mon Sep 17 00:00:00 2001 From: Tim_Tech_Dev Date: Mon, 11 Oct 2021 21:07:58 +0200 Subject: [PATCH 2/3] Remove excess code block --- docs/samples/artnet.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/samples/artnet.md b/docs/samples/artnet.md index c16984c2..ff9cb672 100644 --- a/docs/samples/artnet.md +++ b/docs/samples/artnet.md @@ -117,7 +117,3 @@ Since neither this library nor nodecg-io does not yet contain an abstraction, so > 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) - -``` -Test -``` From a7697df7d4e45d5e01eb1fbe4ce25a0092ab5782 Mon Sep 17 00:00:00 2001 From: Tim_Tech_Dev Date: Tue, 12 Oct 2021 19:59:14 +0200 Subject: [PATCH 3/3] Implement requested changes - Update service/artnet.md - Fix typo in mkdocs.yml --- docs/samples/artnet.md | 56 ++++++++++++------------------------------ mkdocs.yml | 2 +- 2 files changed, 17 insertions(+), 41 deletions(-) diff --git a/docs/samples/artnet.md b/docs/samples/artnet.md index ff9cb672..6a78ca7e 100644 --- a/docs/samples/artnet.md +++ b/docs/samples/artnet.md @@ -47,49 +47,15 @@ The Art-Net example bundle in `samples/artnet-console` demonstrates the ability ### Explanations -**Contents of `./samples/artnet-console/extension/index.ts`** +#### Receiving DMX data ```ts -import { NodeCG } from "nodecg/types/server"; -import { requireService } from "nodecg-io-core"; -import { ArtNetServiceClient } from "nodecg-io-artnet"; - -module.exports = function (nodecg: NodeCG) { - nodecg.log.info("Sample bundle for Art-Net started"); - - const service = requireService(nodecg, "artnet"); - service?.onAvailable((client) => { - // From this point on is the artnet client available - nodecg.log.info("Art-Net console has been updated, setting up interval for sending test payloads."); - - // Receive DMX data - client.onDMX((dmx) => { - // dmx contains an ArtDmx object - nodecg.log.info(dmx.universe, dmx.data); - }); - - // Send DMX data to every channel and universe. - let value = 0; - setInterval(() => { - // send new data every 0,8 seconds. - // This is the official timing for re-transmiting data in the artnet specifciation. - if (++value > 255) value = 0; - for (let universe = 0; universe < 8; universe++) { - client.send( - universe, - // the values of the 512 channels - Array(512).fill(value) - ); - } - }, 800); - }); - - service?.onUnavailable(() => nodecg.log.info("Art-Net console has been unset.")); -}; +client.onDMX((dmx) => { + // dmx contains an ArtDmx object + nodecg.log.info(dmx.universe, dmx.data); +}); ``` -#### Receiving DMX data - The data you receive has the following fields: ```ts @@ -110,7 +76,17 @@ declare class ArtDmx { #### Sending DMX data -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**. +```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- diff --git a/mkdocs.yml b/mkdocs.yml index a6b48893..93edcb1a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -50,7 +50,7 @@ nav: - Services: - Available services: services.md - AHK sample: samples/ahk.md - - Atr-Net sample: samples/artnet.md + - Art-Net sample: samples/artnet.md - Curseforge sample: samples/curseforge.md - Android: samples/android.md - Debug: samples/debug.md