diff --git a/docs/assets/log_in_screen.png b/docs/assets/log_in_screen.png new file mode 100644 index 00000000..df9f0768 Binary files /dev/null and b/docs/assets/log_in_screen.png differ diff --git a/docs/assets/nodcg-io-colored.png b/docs/assets/nodcg-io-colored.png new file mode 100644 index 00000000..6696aa8b Binary files /dev/null and b/docs/assets/nodcg-io-colored.png differ diff --git a/docs/assets/nodcg-io-dashboard.png b/docs/assets/nodcg-io-dashboard.png new file mode 100644 index 00000000..c6c8d706 Binary files /dev/null and b/docs/assets/nodcg-io-dashboard.png differ diff --git a/docs/assets/run_from_vscode.png b/docs/assets/run_from_vscode.png new file mode 100644 index 00000000..aa93962a Binary files /dev/null and b/docs/assets/run_from_vscode.png differ diff --git a/docs/getting_started/install.md b/docs/getting_started/install.md index 47004859..372640fc 100644 --- a/docs/getting_started/install.md +++ b/docs/getting_started/install.md @@ -2,29 +2,36 @@ ## Prerequisites -In order to download necessary tools and to install nodecg-io using the CLI you need network access. +In order to download necessary tools and to install nodecg-io using the CLI you +need network access. ### Required Applications You'll need the following tools: - [Git](https://git-scm.com) -- [Node.JS](https://nodejs.org/en/) v12.0.0 or newer -- [Npm](https://www.npmjs.com/get-npm) 7.0.0 or newer +- [Node.js](https://nodejs.org/en/) v12.0.0 or newer +- [npm](https://www.npmjs.com/get-npm) 7.0.0 or newer - [NodeCG](https://nodecg.dev/) 1.4.0 or newer (1.7.0 or higher recommended) ### Native Build Tools -Some services depend on packages that require native build tools. You _ONLY_ need to install these if you want to use a service that depends on native modules or if you want to install a development version. +Some services depend on packages that require native build tools. You _ONLY_ +need to install these if you want to use a service that depends on native +modules or if you want to install a development version. -The services that require these include StreamDeck, Midi and Serial. Please note that this list might not be up-to-date. +The services that require these include StreamDeck, Midi and Serial. Please note +that this list might not be up-to-date. -Here's how to install the native build tools on the most popular operating systems, if you need them: +Here's how to install the native build tools on the most popular operating +systems, if you need them: #### Windows -For Windows, you'll need the Visual Studio Build Tools, if you have Visual Studio installed you should already have them. -If you don't have Visual Studio just install the Visual Studio Build Tools by running the following command as an **Administrator**: +For Windows, you'll need the Visual Studio Build Tools, if you have Visual +Studio installed you should already have them. If you don't have Visual Studio +just install the Visual Studio Build Tools by running the following command as +an **Administrator**: ```shell npm install -g windows-build-tools @@ -32,17 +39,20 @@ npm install -g windows-build-tools #### Linux -For Linux, you'll need a C++ compiler and some other packages. On Ubuntu/Debian based operating systems run the following command: +For Linux, you'll need a C++ compiler and some other packages. On Ubuntu/Debian +based operating systems run the following command: ```shell sudo apt install build-essential libusb-1.0-0-dev libasound2-dev libudev-dev ``` -For other Linux distros you'll need the corresponding packages, just search on the internet how the packages are named for your specific distro. +For other Linux distros you'll need the corresponding packages, just search on +the internet how the packages are named for your specific distro. #### macOS -For macOS, you'll need the Xcode command line tools. To install them run the following command: +For macOS, you'll need the Xcode command line tools. To install them run the +following command: ```shell xcode-select --install @@ -56,33 +66,119 @@ Install the nodecg-io CLI using the following command: npm install -g nodecg-io-cli ``` -_Note:_ If you are running on Linux, you may need to use `sudo` if your npm installation uses a non-writeable path (default on Ubuntu apt packages, usually does not apply to packages installed using [nvm](https://github.com/nvm-sh/nvm)) +_Note:_ If you are running on Linux, you may need to use `sudo` if your npm +installation uses a non-writeable path (default on Ubuntu apt packages, usually +does not apply to packages installed using [nvm](https://github.com/nvm-sh/nvm)) ## Install nodecg-io using the nodecg-io CLI -With the nodecg-io CLI installed you can run this command inside a nodecg installation to install nodecg-io: +> nodecg-io will always be installed into a `nodecg-io/` directory inside your +> NodeCG installation so that your bundles and all bundles from nodecg-io are +> separated. The CLI will add this path to the loaded bundles in your NodeCG +> configuration automatically, you don't need to worry about it. + +With the nodecg-io CLI installed you can run this command inside a NodeCG +installation to install nodecg-io: ```shell -nodecg-io install +$ nodecg-io install +Installing nodecg-io... ``` -You will get a prompt which asks you which version you want to install. - -- By selecting an actual version (e.g., `0.1`) you create a production install that downloads the required packages from npm and setups a npm workspace to install all dependencies. Here you can choose which services you want to install. - -- By selecting `development` you create a development install that clones the nodecg-io git repo and builds everything from scratch. We only recommend a dev install if you are sure that you want to contribute to nodecg-io. Here you always must install all services. - -For starters, we recommend using the latest non-development version. - -nodecg-io will always be installed into a `nodecg-io/` directory inside your nodecg installation so that your bundles and all bundles from nodecg-io are separated. The CLI will add this path to the loaded bundles in your nodecg configuration automatically, you don't need to worry about it. - -If you want to every change your nodecg-io installation to add/remove a service or change the version, you can always re-run `nodecg-io install`. If a nodecg-io installation is found, its options will be preselected in the prompt. Re-running `nodecg-io install` will also update all packages to the latest patch version, if you have a production installation, and pull the repository and rebuild, if you have a development installation. - -## Start nodecg - -When starting nodecg you should see that all nodecg-io related bundles should be loaded and that you can now access nodecg-io in your nodecg dashboard. - -Now you can either install an already existing bundle that uses nodecg-io, [create a new bundle](./create_new_bundle.md) or [integrate an existing bundle](./existing_bundle.md). +You will get a prompt which asks you which version you want to install: + +
user@computer:~/nodecg$ nodecg-io install
+Installing nodecg-io...
+Detected nodecg installation at /home/user/nodecg.
+? Which version do you want to install? (Use arrow keys) 
+  development 
+❯ 0.1
+ +There are two possible installation types: + +- By selecting an actual version (e.g., `0.1`) you create a production install + that downloads the required packages from npm and setups a npm workspace to + install all dependencies. Here you can choose which services you want to + install. Here you can not easily install our premade examples. + +- By selecting `development` you create a development install that clones the + nodecg-io git repo and builds everything from scratch. We only recommend a + development install if you are sure that you want to contribute to nodecg-io + or want to try an included example. Here you always must install all + services and examples. + +For starters, we recommend using the development version, so you may try our +premade examples. + +### Production install + +
+ Click to see more! + +Because you selected a production install you may select the services to be +included in this next step: + +
user@computer:~/nodecg$ nodecg-io install
+Installing nodecg-io...
+Detected nodecg installation at /home/user/nodecg.
+? Which version do you want to install? 0.1
+? Which services do you want to use? (Press <space> to select, <a> to toggle all,
+<i> to invert selection, and <enter> to proceed)
+❯◯ ahk
+ ◯ android
+ ◯ curseforge
+ ◯ discord
+ ◯ intellij
+ ◯ irc
+ ◯ midi-input
+(Move up and down to reveal more choices)
+ +If you want to every change your nodecg-io installation to add/remove a service +or change the version, you can always re-run `nodecg-io install`. If a nodecg-io +installation is found, its options will be preselected in the prompt. Re-running +`nodecg-io install` will also update all packages to the latest patch version. + +
+ +### Development install + +
+ Click to see more! + +Because you selected a production install you may select to use the samples and +documentation to be included in these next steps: + +
user@computer:~/nodecg$ nodecg-io install
+Installing nodecg-io...
+Detected nodecg installation at /home/user/nodecg.
+? Which version do you want to install? development
+? Would you like to use the provided samples? (y/N)
+ +
user@computer:~/nodecg$ nodecg-io install
+Installing nodecg-io...
+Detected nodecg installation at /home/user/nodecg.
+? Which version do you want to install? development
+? Would you like to use the provided samples? No
+? Would you like to clone the documentation? (y/N)
+ +If you want to every change your nodecg-io installation to add/remove a service +or change the version, you can always re-run `nodecg-io install`. If a nodecg-io +installation is found, its options will be preselected in the prompt. Re-running +`nodecg-io install` will also pull the repository and rebuild it. + +
+ +### Continue reading + +There are many example bundles premade for most services, so you may take a look +at the +[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide (It +will also tell you how to start NodeCG, log in and how to use the GUI). Or you +could directly take a deep dive into our framework and either +[create a new bundle](./create_new_bundle.md) or +[integrate an existing bundle](./existing_bundle.md). There are other bundles +using nodecg-io, witch you could try, so may take a look around GitHub or +GitLab. ## Uninstall nodecg-io @@ -92,4 +188,5 @@ If you want to uninstall nodecg-io you can run the following command: nodecg-io uninstall ``` -This will remove the `nodecg-io` directory inside your nodecg installation and also will remove it from the loaded bundle paths in your nodecg configuration. +This will remove the `nodecg-io` directory inside your NodeCG installation and +also will remove it from the loaded bundle paths in your NodeCG configuration. diff --git a/docs/getting_started/try_example_bundle.md b/docs/getting_started/try_example_bundle.md new file mode 100644 index 00000000..d57abe3a --- /dev/null +++ b/docs/getting_started/try_example_bundle.md @@ -0,0 +1,124 @@ +# Try an included sample + +Trying one of the premade example bundles is a good way to get to know the +framework and especially the selected service. + +> In case you installed the **production** branch of nodecg-io, you are out of +> luck. Because the build process will cause problems if you just take one of +> the samples and rebuild elsewhere. + +If you installed **dev** branch via the `nodecg-io-cli` and did not select the +“use the samples”-option run `nodecg-io install` and select it. + +In case you cloned the repository directly from GitHub, everything should be +included. But you may want to pull recent changes and rebuild the project. + +## Step 1: Run NodeCG + +Now you need to start NodeCG. There are a couple of different ways to do this: + +### Using VS Code + +If you have nodecg-io open in your VS Code instance, you can launch NodeCG using +the `Run and Debug` Explorer View: + +![Run and Debug Explorer View](../assets/run_from_vscode.png) + +### Using the terminal + +You may also launch NodeCG using your terminal with: + +
user@computer:~/nodecg$ npm run start
+
+> nodecg@1.8.1 start
+> node index.js
+
+info: [nodecg/lib/server] Starting NodeCG 1.8.1 (Running on Node.js v16.11.1)
+info: [nodecg-io-core] Minzig!
+
+// A whole host of logging output
+
+info: [nodecg/lib/server] NodeCG running on http://localhost:9090
+ +Now you can open the NodeCG dashboard (by default) under +. + +## Step 2: Log in to nodecg-io + +Now navigate to the `nodecg-io` tab in the NodeCG dashboard. + +If you are logging in for the first time you will have to set your password. + +![Log in screen](../assets/log_in_screen.png) + +Else you simply have to log in with your previously chosen password. + +Now you are looking at the `nodecg-io` config menu. It should look like this: + +![`nodcg-io` config menu](../assets/nodcg-io-dashboard.png) + +## Step 3: Learning how to use the GUI + +The current GUI is just intended to make the project usable, but it is not very +user-friendly. As a more long term solution, a new GUI will be developed that +also focuses on user experience. Until the new GUI is developed, you will have +to arrange yourself with this one. So, to get started: + +![`nodcg-io` colour coded](../assets/nodcg-io-colored.png) + +### In pink: NodeCG Tabs + +Here you will find every NodeCG-bundle that has a dashboard. Here you may select +the [`nodecg-io-debug`](../samples/debug.md)-dashboard, if it is installed. + +### In yellow: Monaco editor + +It is basically only a text editor which is used to save configurations for +service instances. + +### In green: Services section + +Here you may create, update and delete instances of a service. Each instance has +its own name and configuration. The menu will expand depending on the option +selected in the first dropdown. + +_Creating a new service instance_: + +This can be accomplished by selecting the item `'New'`. Then a new dropdown will +be revealed, in witch you may select the service type. Additionally, you must +select an instance name. Then click `'Create'`. The newly created instance +should be selected. + +_Configure a service instance_: + +While a supported service instance is selected, you may change the config in +monaco, then click `'Save'`. + +_Deleting a service instance_: + +This can be accomplished by selecting an existing instance. Then click +`'Delete Instance'`. + +### In violet: Bundles section + +This section has three dropdowns: + +1. Bundle: Here you can select a bundle to configure. +2. Service: If this bundle uses more than one service, you may select the + service to set or unset here. +3. Service Instance: Here you can select one instance of the service type set at + 2 or `none`. + +### In red: Unset all Button + +This button will set the service instance for every bundle/service combination +to none, effectively removing the access to every service from all bundles. +**Caution**: This can not be undone, and you will have to set up all the bundles +again. _The service instances will be unaffected._ + +## Step 4: Configure the sample + +The configurations for every sample bundle differ too greatly from each other to +be included here, so you have to take a look at the documentation for your +sample bundle. You will find it on the left-hand side of this page in the +category `Services`. diff --git a/docs/samples/ahk.md b/docs/samples/ahk.md index 9c6adc83..af6963aa 100644 --- a/docs/samples/ahk.md +++ b/docs/samples/ahk.md @@ -1,25 +1,24 @@ -## Using the AHK sample bundle +## Using the AutoHotkey sample bundle -The AHK sample bundle in `samples/ahk-sendcommand` shows how to send a command to a HotkeylessAHK server. +The AutoHotkey sample bundle in `samples/ahk-sendcommand` shows how to send a +command to a HotkeylessAHK server. ### Prerequisites -- Working NodeCG & nodecg-io installation -- A running [HotkeylessAHK](https://github.com/sebinside/HotkeylessAHK) setup. - -### Configure the ahk sample bundle - -1. Start nodecg with nodecg-io installed. The ahk bundle is currently part of it, so it should also be loaded. +You will need a working `nodecg-io` installation. If you have non yet take a +look at [installation guide](../getting_started/install.md). You may need to +install this bundle, so take a look at the +[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide. It +will also tell you how to log in and how to use the GUI. -2. Go to the `nodecg-io` tab in the nodecg dashboard. +**You also need:** -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 ahk service instance using the left upper menu. +- A running [HotkeylessAHK](https://github.com/sebinside/HotkeylessAHK) setup. -5. Enter the host and port of the HotkeylessAHK Server. +### Configure the AutoHotkey sample bundle - The created instance should be automatically selected, if not select it in the upper left menu. Enter your host and port in monaco (the text-editor on the right) in this format: +1. In NodeCG, create a new ahk service instance. +2. Enter the host and port of the HotkeylessAHK Server: ```json { @@ -30,6 +29,6 @@ The AHK sample bundle in `samples/ahk-sendcommand` shows how to send a command t After entering it, click save. -6. Set the created ahk service instance to the service dependency of the ahk bundle. - -7. A small window with the text “Hello World” should have popped up. +3. Set the sample's (`ahk-sendcommand`) dependency to be the newly created + service instance (of type `ahk`). +4. A small window with the text “Hello World” should have popped up. diff --git a/docs/samples/android.md b/docs/samples/android.md index 583366e3..2e47e033 100644 --- a/docs/samples/android.md +++ b/docs/samples/android.md @@ -1,42 +1,49 @@ ## Using the Android sample bundle -The Android example bundle in `samples/android` shows how to connect to an android device and turn on WLAN. - -1. Clone [this](https://github.com/noeppi-noeppi/nodecg-io-android) Git Repository - -2. Run `gradlew build` (on Windows) or `./gradlew build` (on Linux) inside the cloned repository. - -3. There will be an apk file generated in `app/build/outputs/apk/debug/app-debug.apk`. Install it on the device. - -4. Launch the app. You'll be asked to grant the system alert window permission. This is required because the app will do its work in the background. However, occasionally when user interaction is required, it needs to launch an activity without the user pressing the app icon in the launcher. - -5. Install the android developer tools and make sure you have the `adb` command in your `PATH` - -6. Enable developer options on you device and enable USB debugging there. See [here](https://developer.android.com/studio/debug/dev-options). - +The Android example bundle in `samples/android` shows how to connect to an +Android device and turn on WLAN. + +### Prerequisites + +You will need a working `nodecg-io` installation. If you have non yet take a +look at [installation guide](../getting_started/install.md). You may need to +install this bundle, so take a look at the +[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide. It +will also tell you how to log in and how to use the GUI. + +**You also need:** + +1. Clone [this](https://github.com/noeppi-noeppi/nodecg-io-android) Git + Repository +2. Run `gradlew build` (on Windows) or `./gradlew build` (on Linux) inside the + cloned repository. +3. There will be an apk file generated in + `app/build/outputs/apk/debug/app-debug.apk`. Install it on the Android + device. +4. Launch the app. You'll be asked to grant the system alert window permission. + This is required because the app will do its work in the background. However, + occasionally when user interaction is required, it needs to launch an + activity without the user pressing the app icon in the launcher. +5. Install the android developer tools and make sure you have the `adb` command + in your `PATH` +6. Enable developer options on you device and enable USB debugging there. See + [here](https://developer.android.com/studio/debug/dev-options). 7. Run `adb start-server` - -8. Connect your device via USB. You'll be prompted whether you want to allow USB debugging. Press `Allow`. - +8. Connect your device via USB. You'll be prompted whether you want to allow USB + debugging. Press `Allow`. 9. Run `adb device -l`. The output might look like this: - ``` + ```log ######## device usb:2-1.7 product:######## model:######## device:######## transport_id:2 ``` - The hexadecimal number in the first column is your device ID. You'll need this later. - -10. Start nodecg with nodecg-io installed. The bundle is currently part of it, so it should also be loaded. - -11. Go to the `nodecg-io` tab in the nodecg dashboard. + The hexadecimal number in the first column is your device ID. You'll need + this later. -12. Login using your password. If this is your first run, then enter the password with which you want to encrypt your configurations and credentials. +10. In NodeCG, create a new android service instance. +11. Enter the following: -13. Create a new android service instance using the left upper menu. - -14. Enter the following - - ``` + ```json { "device": "device_id" } @@ -44,8 +51,8 @@ The Android example bundle in `samples/android` shows how to connect to an andro Replace `device_id` with your device ID. -15. Set the created android service instance to the service dependency of the android sample bundle. - - Select the android bundle and the android service in the left bottom menu and then select the service instance that should be used by the android sample bundle (in this case the name of the previously created android instance). + After entering it, click save. -16. You should see that WLAN is now activated on your device. +12. Set the sample's (`android`) dependency to be the newly created service + instance (of type `android`). +13. You should see that WLAN is now activated on your device. diff --git a/docs/samples/artnet.md b/docs/samples/artnet.md index 8c628183..21d50d84 100644 --- a/docs/samples/artnet.md +++ b/docs/samples/artnet.md @@ -1,25 +1,28 @@ ## 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. +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 +You will need a working `nodecg-io` installation. If you have non yet take a +look at [installation guide](../getting_started/install.md). You may need to +install this bundle, so take a look at the +[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide. It +will also tell you how to log in and how to use the GUI. -1. Start nodecg with nodecg-io installed. The artnet-console sample bundle is currently part of it, so it should also be loaded. +**You also need:** -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 Art-Net service instance using the left upper menu. +- A working Art-Net Node in the current network -5. Enter the needed option. +### Configure the Art-Net sample bundle - 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: +1. In NodeCG, create a new Art-Net service instance. +2. Enter the host to witch the service should broadcast: **Host** @@ -33,17 +36,12 @@ The Art-Net example bundle in `samples/artnet-console` demonstrates the ability 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 Art-Net service instance to the service dependency of the artnet-console bundle. + You may overwrite this broadcast address in code with + `client.bind("host address");`. - Select the artnet-console bundle and the Art-Net 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 Art-Net instance). - -7. Check the nodecg logs - - You should see data logged. +3. Set the sample's (`artnet-console`) dependency to be the newly created + service instance (of type `artnet`). +4. Check the NodeCG logs. You should see data logged. ### Explanations @@ -66,7 +64,12 @@ declare class ArtDmx { physical: number; universe: number; data: number[]; - constructor(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; @@ -87,10 +90,12 @@ setInterval(() => { }, 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**. +_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). +> 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/curseforge.md b/docs/samples/curseforge.md index c28822d0..cdc01b74 100644 --- a/docs/samples/curseforge.md +++ b/docs/samples/curseforge.md @@ -1,16 +1,20 @@ ## Using the CurseForge sample bundle -The CurseForge example bundle in `samples/curseforge` demonstrates the ability to search for different add-ons with the ID or search with specific values for matching add-ons. Here is a guide how to get it working. +The CurseForge example bundle in `samples/curseforge` demonstrates the ability +to search for different add-ons with the ID or search with specific values for +matching add-ons. Here is a guide how to get it working. ### Prerequisites -- Working NodeCG & nodecg-io installation +You will need a working `nodecg-io` installation. If you have non yet take a +look at [installation guide](../getting_started/install.md). You may need to +install this bundle, so take a look at the +[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide. It +will also tell you how to log in and how to use the GUI. ### Configure the CurseForge bundle -1. Start NodeCG with nodecg-io installed. The CurseForge bundle is currently part of it, so it should also be loaded. -2. Login using your password. If this is your first run, then enter the password with which you want to encrypt your configurations and credentials. -3. Create a new CurseForge service instance using the left upper menu. -4. Set the CurseForge service instance to the service dependency of the CurseForge bundle. - Select the CurseForge bundle and the CurseForge service in the left bottom menu and then select the service instance that should be used by the CurseForge bundle (in this case the name of the previously created CurseForge instance). -5. Check the NodeCG logs. You should see two lists of add-ons. +1. In NodeCG, create a new CurseForge service instance. +2. Set the sample's (`curseforge`) dependency to be the newly created service + instance (of type `curseforge`). +3. Check the NodeCG logs. You should see two lists of add-ons. diff --git a/docs/samples/dbus-ratbagd.md b/docs/samples/dbus-ratbagd.md index f1691ea5..1756ab0b 100644 --- a/docs/samples/dbus-ratbagd.md +++ b/docs/samples/dbus-ratbagd.md @@ -1,38 +1,32 @@ -## Using the DBus ratbagd sample bundle +## Using the D-Bus ratbagd sample bundle -The dbus-ratbagd example bundle in `samples/dbus-ratbagd` demonstrates how to access all devices supported by ratbagd. Here is a guide to how to get it working. +The `dbus-ratbagd` example bundle in `samples/dbus-ratbagd` demonstrates how to +access all devices supported by ratbagd. Here is a guide to how to get it +working. ### Prerequisites -- Working NodeCG & nodecg-io installation -- [ratbagd](https://github.com/libratbag/libratbag) - -### Configure the DBus ratbagd sample bundle - -1. Start nodecg with nodecg-io installed. The dbus-ratbagd 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. +You will need a working `nodecg-io` installation. If you have non yet take a +look at [installation guide](../getting_started/install.md). You may need to +install this bundle, so take a look at the +[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide. It +will also tell you how to log in and how to use the GUI. -4. Create a new dbus service instance using the left upper menu. +**You also need:** -5. Configure the dbus service - - There should not be any additional configuration needed for the dbus service. Just enter an empty json object like this: - - ```json - {} - ``` - - After entering it, click save. +- [ratbagd](https://github.com/libratbag/libratbag) - _Note:_ If you don't see monaco on the right, try reloading the page. +### Configure the DBus ratbagd sample bundle -6. Set the created dbus service instance to the service dependency of the dbus-ratbagd bundle. +1. In NodeCG, create a new D-Bus service instance. +2. Configure the D-Bus service + There should not be any additional configuration needed for the D-Bus + service. - Select the dbus-ratbagd bundle and the dbus service in the left bottom menu and then select the service instance that should be used by the dbus-ratbagd sample bundle (in this case the name of the previously created dbus instance). +3. Set the sample's (`dbus-ratbagd`) dependency to be the newly created service + instance (of type `dbus`). -7. Check the nodecg logs +4. Check the NodeCG logs: - You should see an error or a success message and a list of connected device names + You should see an error or a success message and a list of connected device + names. diff --git a/docs/samples/debug.md b/docs/samples/debug.md index adb1f844..267bb432 100644 --- a/docs/samples/debug.md +++ b/docs/samples/debug.md @@ -1,17 +1,22 @@ ## Using the Debug sample bundle -The Debug Helper example bundle in `samples/debug` demonstrates the ability to use the debug helper to send same sample data to your bundle, so you can trigger different features and test/debug them. +The Debug Helper example bundle in `samples/debug` demonstrates the ability to +use the debug helper to send same sample data to your bundle, so you can trigger +different features and test/debug them. ### Prerequisites -- Working NodeCG & nodecg-io installation +You will need a working `nodecg-io` installation. If you have non yet take a +look at [installation guide](../getting_started/install.md). You may need to +install this bundle, so take a look at the +[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide. It +will also tell you how to log in and how to use the GUI. ### Configure the Debug sample bundle -1. Start NodeCG with nodecg-io installed. The Debug sample bundle is currently part of it, so it should also be loaded. -2. Login using your password. If this is your first run, then enter the password with which you want to encrypt your configurations and credentials. -3. Create a new Debug service instance using the left upper menu. -4. Set the Debug service instance to the service dependency of the Debug sample bundle. - Select the Debug sample bundle and the Debug service in the left bottom menu and then select the service instance that should be used by the Debug sample bundle (in this case the name of the previously created Debug instance). -5. Go to the nodecg-io-debug dashboard and use some buttons or other inputs. -6. Check the nodecg log. It should contain a message for each action you did and the passed values. +1. In NodeCG, create a new Debug service instance. +2. Set the sample's (`debug`) dependency to be the newly created service + instance (of type `debug`). +3. Go to the nodecg-io-debug dashboard and use some buttons or other inputs. +4. Check the NodeCG log. It should contain a message for each action you did and + the passed values. diff --git a/docs/samples/discord-rpc.md b/docs/samples/discord-rpc.md index 3beaae24..29540fe5 100644 --- a/docs/samples/discord-rpc.md +++ b/docs/samples/discord-rpc.md @@ -1,27 +1,28 @@ ## Using the Discord RPC sample bundle -The discord-rpc example bundle in `samples/discord-rpc` demonstrates the ability to access a locally running discord client. Here is a guide to how to get it working. +The Discord Rich Presence example bundle in `samples/discord-rpc` demonstrates +the ability to access a locally running discord client. Here is a guide to how +to get it working. ### Prerequisites -- Working NodeCG & nodecg-io installation -- A discord application with permissions `indentify` and `rpc` - -_Note:_ If you don't have an application yet, you can create one [here](https://discord.com/developers/applications) - -### Configure the Discord RPC sample bundle - -1. Start nodecg with nodecg-io installed. The discord-rpc bundle is currently part of it so it should also be loaded. +You will need a working `nodecg-io` installation. If you have non yet take a +look at [installation guide](../getting_started/install.md). You may need to +install this bundle, so take a look at the +[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide. It +will also tell you how to log in and how to use the GUI. -2. Go to the `nodecg-io` tab in the nodecg dashboard. +**You also need:** -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. +- A discord application with permissions `indentify` and `rpc` -4. Create a new discord-rpc service instance using the left upper menu. +_Note:_ If you don't have an application yet, you can create one +[here](https://discord.com/developers/applications) -5. Enter required information. +### Configure the Discord RPC sample bundle - The created instance should be automatically selected, if not select it in the upper left menu. Enter your information in monaco (the text-editor on the right) in this format: +1. In NodeCG, create a new `discord-rpc` service instance. +2. Enter the `clientId` and `clientSecret` for the service: ```json { @@ -32,12 +33,9 @@ _Note:_ If you don't have an application yet, you can create one [here](https:// After entering it, click save. - _Note:_ If you don't see monaco on the right, try reloading the page. - -6. Set the created discord-rpc service instance to the service dependency of the discord-rpc bundle. - - Select the discord-rpc bundle and the discord-rpc service in the left bottom menu and then select the service instance that should be used by the discord-rpc sample bundle (in this case the name of the previously created discord-rpc instance). - -7. Check the nodecg logs +3. Set the sample's (`discord-rpc`) dependency to be the newly created service + instance (of type `discord-rpc`). +4. Check the NodeCG logs: - You should see an error or a success message displaying your discord username. + You should see an error or a success message displaying your discord + username. diff --git a/docs/samples/discord.md b/docs/samples/discord.md index a9c6e64c..008fe712 100644 --- a/docs/samples/discord.md +++ b/docs/samples/discord.md @@ -1,27 +1,29 @@ ## Using the Discord sample bundle -The Discord-guild-chat example bundle in `samples/discord-guild-chat` demonstrates the ability to reply with `pong` to messages which are equal to `!ping` or `ping`. Here is a guide to how to get it working. +The Discord-guild-chat example bundle in `samples/discord-guild-chat` +demonstrates the ability to reply with `pong` to messages which are equal to +`!ping` or `ping`. Here is a guide to how to get it working. ### Prerequisites -- Working NodeCG & nodecg-io installation -- a Discord Bot token +You will need a working `nodecg-io` installation. If you have non yet take a +look at [installation guide](../getting_started/install.md). You may need to +install this bundle, so take a look at the +[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide. It +will also tell you how to log in and how to use the GUI. -_Note:_ If you don't have such a token yet, you can follow [this](https://discordjs.guide/preparations/setting-up-a-bot-application.html) guide. +**You also need:** -### Configure the Discord sample bundle - -1. Start nodecg with nodecg-io installed. The Discord-guild-chat 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. +- A Discord Bot token -4. Create a new discord service instance using the left upper menu. +_Note:_ If you don't have such a token yet, you can follow +[this](https://discordjs.guide/preparations/setting-up-a-bot-application.html) +guide. -5. Enter your bot token. +### Configure the Discord sample bundle - The created instance should be automatically selected, if not select it in the upper left menu. Enter your Bot token in monaco (the text-editor on the right) in this format: +1. In NodeCG, create a new discord service instance. +2. Enter your bot token: ```json { @@ -31,12 +33,8 @@ _Note:_ If you don't have such a token yet, you can follow [this](https://discor After entering it, click save. - _Note:_ If you don't see monaco on the right, try reloading the page. - -6. Set the created discord service instance to the service dependency of the Discord-guild-chat bundle. - - Select the Discord-guild-chat bundle and the Discord service in the left bottom menu and then select the service instance that should be used by the Discord-guild-chat bundle (in this case the name of the previously created discord instance). - -7. Check the nodecg logs +3. Set the sample's (`discord-guild-chat`) dependency to be the newly created + service instance (of type `discord`). +4. Check the NodeCG logs: You should see an error or a Login message. diff --git a/docs/samples/github.md b/docs/samples/github.md index 9af59120..0c1a5f48 100644 --- a/docs/samples/github.md +++ b/docs/samples/github.md @@ -1,27 +1,28 @@ ## Using the GitHub sample bundle -The GitHub example bundle in `samples/github` demonstrates the ability to access the GitHub rest API. Here is a guide to how to get it working. +The GitHub example bundle in `samples/github` demonstrates the ability to access +the GitHub rest API. Here is a guide to how to get it working. ### Prerequisites -- Working NodeCG & nodecg-io installation -- a GitHub token +You will need a working `nodecg-io` installation. If you have non yet take a +look at [installation guide](../getting_started/install.md). You may need to +install this bundle, so take a look at the +[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide. It +will also tell you how to log in and how to use the GUI. -_Note:_ If you don't have a token yet, you can create one [here](https://github.com/settings/tokens/new). The token requires at least the `repo` scope. +**You also need:** -### Configure the GitHub sample bundle - -1. Start nodecg with nodecg-io installed. The GitHub 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. +- A GitHub token -4. Create a new GitHub service instance using the left upper menu. +_Note:_ If you don't have a token yet, you can create one +[here](https://github.com/settings/tokens/new). The token requires at least the +`repo` scope. -5. Enter the GitHub token. +### Configure the GitHub sample bundle - The created instance should be automatically selected, if not select it in the upper left menu. Enter your GitHub token in monaco (the text-editor on the right) in this format: +1. In NodeCG, create a new GitHub service instance. +2. Enter the GitHub token: ```json { @@ -31,12 +32,9 @@ _Note:_ If you don't have a token yet, you can create one [here](https://github. After entering it, click save. - _Note:_ If you don't see monaco on the right, try reloading the page. - -6. Set the created GitHub service instance to the service dependency of the GitHub bundle. - - Select the GitHub bundle and the GitHub service in the left bottom menu and then select the service instance that should be used by the GitHub sample bundle (in this case the name of the previously created GitHub instance). - -7. Check the nodecg logs +3. Set the sample's (`github`) dependency to be the newly created service + instance (of type `github`). +4. Check the NodeCG logs: - You should see an error or a success message and a list of all your repositories. + You should see an error or a success message and a list of all your + repositories. diff --git a/docs/samples/gsheets.md b/docs/samples/gsheets.md index 9311dc3f..2205fe0c 100644 --- a/docs/samples/gsheets.md +++ b/docs/samples/gsheets.md @@ -1,29 +1,32 @@ ## Using the gsheets sample bundle -The gsheets bundle in `samples/gsheets` demonstrates the ability of retrieving all rows where column A is filled. Here is a guide to how to get it working. +The gsheets bundle in `samples/gsheets` demonstrates the ability of retrieving +all rows where column A is filled. Here is a guide to how to get it working. ### Prerequisites -- Working NodeCG & nodecg-io installation +You will need a working `nodecg-io` installation. If you have non yet take a +look at [installation guide](../getting_started/install.md). You may need to +install this bundle, so take a look at the +[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide. It +will also tell you how to log in and how to use the GUI. + +**You also need:** + - Google cloud API OAuth access (client ID, client Secret) - Grant `Google Sheets API v4` access at the project's dashboard. - - Shortcut URL: > + - Shortcut URL: + > -_Note:_ If you don't have such a key yet, you can generate them like [this](https://developers.google.com/identity/protocols/oauth2/web-server#creatingcred). As the redirect URI add . +_Note:_ If you don't have such a key yet, you can generate them like +[this](https://developers.google.com/identity/protocols/oauth2/web-server#creatingcred). +As the redirect URI add +. ### Configure the gsheets sample bundle -1. Start nodecg with nodecg-io installed. The gsheets 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 googleapis service instance using the left upper menu. - -5. Enter credentials for googleapis. - - The created instance should be automatically selected, if not select it in the upper left menu. Enter your gsheets OAuth credentials in monaco (the text-editor on the right) in this format: +1. In NodeCG, create a new googleapis service instance. +2. Enter the credentials for googleapis: ```json { @@ -35,13 +38,12 @@ _Note:_ If you don't have such a key yet, you can generate them like [this](http After entering it, click save. - _Note:_ If you don't see monaco on the right, try reloading the page. - _Note:_ You can add multiple scopes if the googleapis instance is used for multiple bundles. - -6. Set the created googleapis service instance to the service dependency of the gsheets bundle. - - Select the gsheets bundle and the googleapis service in the left bottom menu and then select the service instance that should be used by the gsheets bundle (in this case the name of the previously created googleapis instance). + _Note:_ You can add multiple scopes if the googleapis instance is used for + multiple bundles. -7. Check the nodecg logs +3. Set the sample's (`gsheets`) dependency to be the newly created service + instance (of type `googleapis`). +4. Check the NodeCG logs: - You should see an error or a success message that is hardcoded in `samples/gsheets/extension/index.ts`. + You should see an error or a success message that is hardcoded in + `samples/gsheets/extension/index.ts`. diff --git a/docs/samples/intellij.md b/docs/samples/intellij.md index 2e57d957..c93325ea 100644 --- a/docs/samples/intellij.md +++ b/docs/samples/intellij.md @@ -1,28 +1,34 @@ ## Using the IntelliJ sample bundle -The IntelliJ example bundle in `samples/intellij-integration` Shows how to connect to a JetBrains IDE and print all installed plugins. Here is a guide to how to get it working: +The IntelliJ example bundle in `samples/intellij-integration` Shows how to +connect to a JetBrains IDE and print all installed plugins. Here is a guide to +how to get it working: -1. clone [this](https://github.com/noeppi-noeppi/nodecg-io-intellij) Git Repository +### Prerequisites -2. Make sure you've Java 11 or newer installed. - -3. Run `gradlew build` (on Windows) or `./gradlew build` (on Linux) inside the cloned repository. - -4. Inside your JetBrains IDE go to `Settings` and then `Plugins`. Click on the little gear in the top right corner. Then click `Install from file`. - -5. Navigate to `path to your cloned repository/build/libs` and select the jar file there. - -6. Restart the IDE +You will need a working `nodecg-io` installation. If you have non yet take a +look at [installation guide](../getting_started/install.md). You may need to +install this bundle, so take a look at the +[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide. It +will also tell you how to log in and how to use the GUI. -7. Start nodecg with nodecg-io installed. The bundle is currently part of it, so it should also be loaded. +**You also need:** -8. Go to the `nodecg-io` tab in the nodecg dashboard. - -9. Login using your password. If this is your first run, then enter the password with which you want to encrypt your configurations and credentials. +1. Clone [this](https://github.com/noeppi-noeppi/nodecg-io-intellij) Git + Repository. +2. Make sure you've Java 11 or newer installed. +3. Run `gradlew build` (on Windows) or `./gradlew build` (on Linux) inside the + cloned repository. +4. Inside your JetBrains IDE go to `Settings` and then `Plugins`. Click on the + little gear in the top right corner. Then click `Install from file`. +5. Navigate to `path to your cloned repository/build/libs` and select the jar + file there. +6. Restart the IDE. -10. Create a new IntelliJ service instance using the left upper menu. +### Configure the IntelliJ sample bundle -11. Enter the following +1. In NodeCG, create a new IntelliJ service instance. +2. Enter the host and port of your IDE's HTTP server: ``` { @@ -30,12 +36,14 @@ The IntelliJ example bundle in `samples/intellij-integration` Shows how to conne } ``` - This tells nodecg-io to look for your IDE's HTTP server on your computer at port `19524`. If you want it to run on another port, please follow the guidelines [here](https://github.com/noeppi-noeppi/nodecg-io-intellij/blob/master/README.md). - -12. Set the created IntelliJ service instance to the service dependency of the sample-intellij bundle. - - Select the sample-intellij bundle and the IntelliJ service in the left bottom menu and then select the service instance that should be used by the sample-intellij bundle (in this case the name of the previously created IntelliJ instance). + This tells nodecg-io to look for your IDE's HTTP server on your computer at + port `19524`. If you want it to run on another port, please follow the + guidelines + [here](https://github.com/noeppi-noeppi/nodecg-io-intellij/blob/master/README.md). -13. Check the nodecg logs +3. Set the sample's (`intellij-integration`) dependency to be the newly created + service instance (of type `intellij`). +4. Check the NodeCG logs: - You should see an error or a list of all plugins installed at your IDE including the preinstalled ones by JetBrains. + You should see an error or a list of all plugins installed at your IDE + including the preinstalled ones by JetBrains. diff --git a/docs/samples/irc.md b/docs/samples/irc.md index 94f7af69..8f57af26 100644 --- a/docs/samples/irc.md +++ b/docs/samples/irc.md @@ -1,24 +1,21 @@ ## Using the IRC sample bundle -The IRC example bundle in `samples/irc` demonstrates the ability to get access to an IRC chat. This sample is designed to log the twitch IRC chat of skate702. +The IRC example bundle in `samples/irc` demonstrates the ability to get access +to an IRC chat. This sample is designed to log the twitch IRC chat of skate702. ### Prerequisites -- Working NodeCG & nodecg-io installation +You will need a working `nodecg-io` installation. If you have non yet take a +look at [installation guide](../getting_started/install.md). You may need to +install this bundle, so take a look at the +[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide. It +will also tell you how to log in and how to use the GUI. ### Configure the IRC sample bundle -1. Start nodecg with nodecg-io installed. The IRC 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 IRC service instance using the left upper menu. - -5. Enter credentials for IRC. - - The created instance should be automatically selected, if not select it in the upper left menu. In this example we will anonymously connect to the twitch IRC chat. Enter the config in this format: +1. In NodeCG, create a new IRC service instance. +2. Enter the credentials for IRC. In this example we will “anonymously” connect + to the twitch IRC chat. Enter the host, port, and nick in this format: ```json { @@ -32,12 +29,10 @@ The IRC example bundle in `samples/irc` demonstrates the ability to get access t After entering it, click save. - _Note:_ If you don't see monaco on the right, try reloading the page. - -6. Set the created IRC service instance to the service dependency of the IRC sample bundle. - - Select the IRC sample bundle and the IRC service in the left bottom menu and then select the service instance that should be used by the IRC sample bundle (in this case the name of the previously created IRC instance). - -7. Check the nodecg logs +3. Set the sample's (`irc`) dependency to be the newly created service instance + (of type `irc`). +4. Check the NodeCG logs: - You should see an error or a success message and all twitch messages that are written in the twitch channel that is hardcoded in `samples/irc/extension/index.ts`. + You should see an error or a success message and all twitch messages that + are written in the twitch channel that is hardcoded in + `samples/irc/extension/index.ts`. diff --git a/docs/samples/midi-input.md b/docs/samples/midi-input.md index d7dbe306..b86d4239 100644 --- a/docs/samples/midi-input.md +++ b/docs/samples/midi-input.md @@ -1,25 +1,25 @@ ## Using the midi-input sample bundle -The midi-input example bundle in `samples/midi-input` demonstrates the ability to read data from a midi device. +The midi-input example bundle in `samples/midi-input` demonstrates the ability +to read data from a midi device. ### Prerequisites -- Working NodeCG & nodecg-io installation -- A midi device that can be connected to your computer - -### Configure the midi-input sample bundle +You will need a working `nodecg-io` installation. If you have non yet take a +look at [installation guide](../getting_started/install.md). You may need to +install this bundle, so take a look at the +[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide. It +will also tell you how to log in and how to use the GUI. -1. Start nodecg with nodecg-io installed. The Twitch-chat bundle is currently part of it, so it should also be loaded. +**You also need:** -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. +- A midi device that can be connected to your computer -4. Create a new midi-input service instance using the left upper menu. +### Configure the midi-input sample bundle -5. Enter your device information +1. In NodeCG, create a new midi-input service instance. - The created instance should be automatically selected, if not select it in the upper left menu. Enter the name of your device in monaco (the text-editor on the right) in this format: +2. Enter your device information: ```json { @@ -27,20 +27,20 @@ The midi-input example bundle in `samples/midi-input` demonstrates the ability t } ``` - After entering it, click save. - **Note:** A script is provided to list all inputs and outputs. It can be run from the sample directory `samples/midi-input` using the command `npm run list`. The devices should be listed with their device names and some other stuff. + After entering it, click save. + **Note:** A script is provided to list all inputs and outputs. It can be run + from the sample directory `samples/midi-input` using the command + `npm run list`. The devices should be listed with their device names and + some other stuff. Under Linux this looks for example like this: ``` nanoKONTROL2:nanoKONTROL2 MIDI 1 28:0 ``` - _Note:_ If you don't see monaco on the right, try reloading the page. - -6. Set the created midi-input service instance to the service dependency of the midi-input sample bundle. - - Select the midi-input bundle and the midi-input service in the left bottom menu and then select the service instance that should be used by the midi-input bundle (in this case the name of the previously created midi-input instance). - -7. Check the nodecg logs +3. Set the sample's (`midi-input`) dependency to be the newly created service + instance (of type `midi-input`). +4. Check the NodeCG logs: - You should see an error or a success message and all midi messages that are sent by the device that is configured. + You should see an error or a success message and all midi messages that are + sent by the device that is configured. diff --git a/docs/samples/midi-io.md b/docs/samples/midi-io.md index e2cde5b9..8bdf9924 100644 --- a/docs/samples/midi-io.md +++ b/docs/samples/midi-io.md @@ -1,25 +1,25 @@ ## Using the midi-io sample bundle -The midi-io example bundle in `samples/midi-io` demonstrates the ability to send/receive data to/from a midi device. +The midi-io example bundle in `samples/midi-io` demonstrates the ability to +send/receive data to/from a midi device. ### Prerequisites -- Working NodeCG & nodecg-io installation -- A midi device that can be connected to your computer - -### Configure the midi-io sample bundle +You will need a working `nodecg-io` installation. If you have non yet take a +look at [installation guide](../getting_started/install.md). You may need to +install this bundle, so take a look at the +[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide. It +will also tell you how to log in and how to use the GUI. -1. Start nodecg with nodecg-io installed. The midi-io bundle is currently part of it, so it should also be loaded. +**You also need:** -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. +- A midi device that can be connected to your computer -4. Create a new midi-input service instance using the left upper menu. +### Configure the midi-io sample bundle -5. Enter your device information +1. In NodeCG, create a new midi-input service instance. - The created instance should be automatically selected, if not select it in the upper left menu. Enter the name of your device in monaco (the text-editor on the right) in this format: +2. Enter your device information: ```json { @@ -27,33 +27,36 @@ The midi-io example bundle in `samples/midi-io` demonstrates the ability to send } ``` - After entering it, click save. - **Note:** A script is provided to list all inputs and outputs. It can be run from the sample directory `samples/midi-io` using the command `npm run list`. The devices should be listed with their device names and some other stuff. + After entering it, click save. + **Note:** A script is provided to list all inputs and outputs. It can be run + from the sample directory `samples/midi-io` using the command + `npm run list`. The devices should be listed with their device names and + some other stuff. Under Linux this looks for example like this: ``` nanoKONTROL2:nanoKONTROL2 MIDI 1 28:0 ``` - _Note:_ If you don't see monaco on the right, try reloading the page. - -6. Create a new midi-output service instance using the left upper menu. - -7. Repeat step 5 for your midi-output service. In most cases you want to use the same device for input and output. - -8. Set the created midi-output service instance to the service dependency of the midi-io sample bundle. - - Select the midi-io bundle and the midi-output service in the left bottom menu and then select the service instance that should be used by the midi-io bundle (in this case the name of the previously created midi-output instance). - -9. Set the created midi-input service instance to the service dependency of the midi-io sample bundle. +3. Create a new midi-output service instance using the left upper menu. - Select the midi-io bundle and the midi-input service in the left bottom menu and then select the service instance that should be used by the midi-io bundle (in this case the name of the previously created midi-input instance). +4. Set the sample's (`midi-io`) dependencies to be the newly created service + instances (of type `midi-input` & `midi-output`). -10. Check the nodecg logs +5. Check the NodeCG logs: - You should see an error or a success message and midi messages that are received and echoed back to the device that is configured. The messages are only modified, if the received Message is a `Noteon` with a velocity of greater than zero or a control change message with a value of at least 64. `Noteoff` messages are always echoed unmodified. + You should see an error or a success message and midi messages that are + received and echoed back to the device that is configured. The messages are + only modified, if the received Message is a `Noteon` with a velocity of + greater than zero or a control change message with a value of at least 64. + `Noteoff` messages are always echoed unmodified. ### Note -A `Noteon` message with a velocity of 0 should be handled like a `Noteoff` message, so they are echoed unmodified. Otherwise, this would get annoying very fast. -If a control change is assigned to the push-button values of 64 and up are interpreted as on and values lower than that are interpreted as off. Most somewhat modern Midi devices send 127 as on and 0 as off, but 63 and 64 should also be sufficient. +A `Noteon` message with a velocity of 0 should be handled like a `Noteoff` +message, so they are echoed unmodified. Otherwise, this would get annoying very +fast. +If a control change is assigned to the push-button values of 64 and up are +interpreted as on and values lower than that are interpreted as off. Most +somewhat modern Midi devices send 127 as on and 0 as off, but 63 and 64 should +also be sufficient. diff --git a/docs/samples/midi-output.md b/docs/samples/midi-output.md index b7fb2490..788c4c77 100644 --- a/docs/samples/midi-output.md +++ b/docs/samples/midi-output.md @@ -1,25 +1,25 @@ ## Using the midi-output sample bundle -The midi-output example bundle in `samples/midi-output` demonstrates the ability to send data to a midi device. +The midi-output example bundle in `samples/midi-output` demonstrates the ability +to send data to a midi device. ### Prerequisites -- Working NodeCG & nodecg-io installation -- A midi device that can be connected to your computer - -### Configure the midi-output sample bundle - -1. Start nodecg with nodecg-io installed. The midi-output bundle is currently part of it, so it should also be loaded. +You will need a working `nodecg-io` installation. If you have non yet take a +look at [installation guide](../getting_started/install.md). You may need to +install this bundle, so take a look at the +[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide. It +will also tell you how to log in and how to use the GUI. -2. Go to the `nodecg-io` tab in the nodecg dashboard. +**You also need:** -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. +- A midi device that can be connected to your computer -4. Create a new midi-output service instance using the left upper menu. +### Configure the midi-output sample bundle -5. Enter your device information +1. In NodeCG, create a new midi-output service instance. - The created instance should be automatically selected, if not select it in the upper left menu. Enter the name of your device in monaco (the text-editor on the right) in this format: +2. Enter your device information: ```json { @@ -27,24 +27,32 @@ The midi-output example bundle in `samples/midi-output` demonstrates the ability } ``` - After entering it, click save. - **Note:** A script is provided to list all inputs and outputs. It can be run from the sample directory `samples/midi-output` using the command `npm run list`. The devices should be listed with their device names and some other stuff. + After entering it, click save. + **Note:** A script is provided to list all inputs and outputs. It can be run + from the sample directory `samples/midi-output` using the command + `npm run list`. The devices should be listed with their device names and + some other stuff. Under Linux this looks for example like this: ``` nanoKONTROL2:nanoKONTROL2 MIDI 1 28:0 ``` - _Note:_ If you don't see monaco on the right, try reloading the page. - -6. Set the created midi-output service instance to the service dependency of the midi-output sample bundle. - - Select the midi-output bundle and the midi-output service in the left bottom menu and then select the service instance that should be used by the midi-output bundle (in this case the name of the previously created midi-output instance). +3. Set the sample's (`midi-output`) dependency to be the newly created service + instance (of type `midi-output`). -7. Check the nodecg logs +4. Check the NodeCG logs: - You should see an error or a success message and random midi messages should be sent to the device that is configured. The messages are only `Noteon` messages and have a random note and velocity value ranging 0-127. The channels they are sent from are either channel 0 or 1, but the midi protocol supports up to 16 channels, so it could technically range from 0-15. + You should see an error or a success message and random midi messages should + be sent to the device that is configured. The messages are only `Noteon` + messages and have a random note and velocity value ranging 0-127. The + channels they are sent from are either channel 0 or 1, but the midi protocol + supports up to 16 channels, so it could technically range from 0-15. ### Note -Only sending `Noteon` messages is sufficient for most midi, because most of them don't really care if you use proper `Noteoff` messages or simply send a `Noteon` with a velocity of 0. This is due to the early days of midi, when integrated circuits were expensive. Allowing a velocity of 0 as replacement for `Noteoff` made instruments featuring midi more affordable. +Only sending `Noteon` messages is sufficient for most midi, because most of them +don't really care if you use proper `Noteoff` messages or simply send a `Noteon` +with a velocity of 0. This is due to the early days of midi, when integrated +circuits were expensive. Allowing a velocity of 0 as replacement for `Noteoff` +made instruments featuring midi more affordable. diff --git a/docs/samples/mqtt-client.md b/docs/samples/mqtt-client.md index b152db66..a22be8ca 100644 --- a/docs/samples/mqtt-client.md +++ b/docs/samples/mqtt-client.md @@ -1,23 +1,31 @@ ## Using the MQTT-client sample bundle -The MQTT-client sample bundle in `samples/mqtt-client` shows how to connect to an MQTT server. This client is based on the [MQTT.js](https://github.com/mqttjs/MQTT.js) package. +The MQTT-client sample bundle in `samples/mqtt-client` shows how to connect to +an MQTT server. This client is based on the +[MQTT.js](https://github.com/mqttjs/MQTT.js) package. ### Prerequisites -- Working NodeCG & nodecg-io installation +You will need a working `nodecg-io` installation. If you have non yet take a +look at [installation guide](../getting_started/install.md). You may need to +install this bundle, so take a look at the +[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide. It +will also tell you how to log in and how to use the GUI. + +**You also need:** + - MQTT-server ### Configure the MQTT-client sample bundle -1. Start NodeCG with nodecg-io installed. The mqtt-client 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 mqtt-client service instance using the left upper menu. +1. In NodeCG, create a new mqtt-client service instance. -5. Enter the connection parameters of the mqtt server. The URL should be in following the pattern `://
:`. Allowed protocols are: `mqtt`, `mqtts`, `tcp`, `tls`, `ws`, `wss`. +2. Enter the connection parameters of the mqtt server. The URL should be in + following the pattern `://
:`. Allowed protocols are: + `mqtt`, `mqtts`, `tcp`, `tls`, `ws`, `wss`. - In case your server needs authentication, set the `username` and `password` fields otherwise remove them from the configuration. - The created instance should be automatically selected, if not select it in the upper left menu. Enter your configuration in monaco (the text-editor on the right) in this format: + In case your server needs authentication, set the `username` and `password` + fields otherwise remove them from the configuration: ```json { @@ -30,5 +38,7 @@ The MQTT-client sample bundle in `samples/mqtt-client` shows how to connect to a After entering it, click save. -6. Set the created mqtt-client service instance to the service dependency of the mqtt-client bundle. -7. The console should display if the connection was successfully established and should show inbound messages on the subscribed topic. +3. Set the sample's (`mqtt-client`) dependency to be the newly created service + instance (of type `mqtt-client`). +4. The console should display if the connection was successfully established and + should show inbound messages on the subscribed topic. diff --git a/docs/samples/nanoleaf.md b/docs/samples/nanoleaf.md index 0d5d1289..3ee86236 100644 --- a/docs/samples/nanoleaf.md +++ b/docs/samples/nanoleaf.md @@ -1,25 +1,26 @@ ## Using the Nanoleaf sample bundle -The Nanoleaf example bundle in `samples/nanoleaf` demonstrates the ability to control your nanoleaf lights. This example code sets all panels to an orange colour. Here is a guide to how to get it working. +The Nanoleaf example bundle in `samples/nanoleaf` demonstrates the ability to +control your nanoleaf lights. This example code sets all panels to an orange +colour. Here is a guide to how to get it working. ### Prerequisites -- Working NodeCG and a nodecg-io installation -- IP address of your nanoleaf controller - -### Configure the nanoleaf sample bundle +You will need a working `nodecg-io` installation. If you have non yet take a +look at [installation guide](../getting_started/install.md). You may need to +install this bundle, so take a look at the +[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide. It +will also tell you how to log in and how to use the GUI. -1. Start nodecg with nodecg-io installed. The nanoleaf sample bundle is currently part of it, so it should also be loaded. +**You also need:** -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. +- IP address of your nanoleaf controller -4. Create a new nanoleaf service instance using the left upper menu. +### Configure the nanoleaf sample bundle -5. Enter configuration. +1. In NodeCG, create a new nanoleaf service instance. - The created instance should be automatically selected, if not select it in the upper left menu. Enter your nanoleaf controller IP address in this format (change the IP accordingly): +2. Enter the IP address of your nanoleaf controller: ```json { @@ -27,16 +28,13 @@ The Nanoleaf example bundle in `samples/nanoleaf` demonstrates the ability to co } ``` - Before clicking save put your nanoleaf controller into pairing mode by holding the on-off button for 5-7 seconds till the LED starts flashing. + Before clicking save put your nanoleaf controller into pairing mode by + holding the on-off button for 5-7 seconds till the LED starts flashing. After entering your config and entering pairing mode, click save. - _Note:_ If you don't see monaco on the right, try reloading the page. - -6. Set the created nanoleaf service instance to the service dependency of the nanoleaf sample bundle. - - Select the nanoleaf sample bundle and the nanoleaf service in the left bottom menu and then select the service instance that should be used by the nanoleaf sample bundle (in this case the name of the previously created nanoleaf instance). - -7. If everything worked, your nanoleafs should now shine orange. +3. Set the sample's (`nanoleaf`) dependency to be the newly created service + instance (of type `nanoleaf`). - If not you should check the nodecg logs for any errors. +4. If everything worked, your nanoleafs should now shine orange. + If not you should check the NodeCG logs for any errors. diff --git a/docs/samples/obs.md b/docs/samples/obs.md index de3965b7..32a7347d 100644 --- a/docs/samples/obs.md +++ b/docs/samples/obs.md @@ -1,27 +1,30 @@ ## Using the OBS sample bundle -The OBS example bundle in `samples/obs-scenelist` demonstrates the ability to control an OBS instance by listing all available scenes. Here is a guide to how to get it working. +The OBS example bundle in `samples/obs-scenelist` demonstrates the ability to +control an OBS instance by listing all available scenes. Here is a guide to how +to get it working. ### Prerequisites -- Working NodeCG & nodecg-io installation -- OBS with obs-websocket installed - -_Note:_ OBS is available [here](https://obsproject.com/de/download) and obs-websocket with install instructions is available [here](https://github.com/Palakis/obs-websocket/releases). - -### Configure the OBS sample bundle +You will need a working `nodecg-io` installation. If you have non yet take a +look at [installation guide](../getting_started/install.md). You may need to +install this bundle, so take a look at the +[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide. It +will also tell you how to log in and how to use the GUI. -1. Start nodecg with nodecg-io installed. The obs-scenelist bundle is currently part of it, so it should also be loaded. +**You also need:** -2. Go to the `nodecg-io` tab in the nodecg dashboard. +- OBS with obs-websocket installed -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. +_Note:_ OBS is available [here](https://obsproject.com/de/download) and +obs-websocket with install instructions is available +[here](https://github.com/Palakis/obs-websocket/releases). -4. Create a new obs service instance using the left upper menu. +### Configure the OBS sample bundle -5. Enter configuration for obs. +1. In NodeCG, create a new obs service instance. - The created instance should be automatically selected, if not select it in the upper left menu. Enter your obs-websocket connection information in monaco (the text-editor on the right) in this format: +2. Enter the configuration for obs: ```json { @@ -31,16 +34,15 @@ _Note:_ OBS is available [here](https://obsproject.com/de/download) and obs-webs } ``` - If you don't want to use a password, you can just remove the password property from the config. + If you don't want to use a password, you can just remove the password + property from the config. After entering it, click save. - _Note:_ If you don't see monaco on the right, try reloading the page. - -6. Set the created obs service instance to the service dependency of the obs-scenelist bundle. - - Select the obs-scenelist bundle and the OBS service in the left bottom menu and then select the service instance that should be used by the obs-scenelist bundle (in this case the name of the previously created OBS instance). +3. Set the sample's (`obs-scenelist`) dependency to be the newly created service + instance (of type `obs`). -7. Check the nodecg logs +4. Check the NodeCG logs: - You should see an error or a success message and the names of all you scenes that you have set in OBS. + You should see an error or a success message and the names of all you scenes + that you have set in OBS. diff --git a/docs/samples/philipshue.md b/docs/samples/philipshue.md index b1d20c15..482a4e9d 100644 --- a/docs/samples/philipshue.md +++ b/docs/samples/philipshue.md @@ -1,25 +1,29 @@ ## Using the Philips Hue sample bundle -The philipshue-lights example bundle in `samples/philipshue-lights` demonstrates the ability to connect to the Philips Hue bridge and control Philips Hue accessories. +The philipshue-lights example bundle in `samples/philipshue-lights` demonstrates +the ability to connect to the Philips Hue bridge and control Philips Hue +accessories. ### Prerequisites -- Working NodeCG & nodecg-io installation -- A Philips Hue bridge with some connected accessories - -### Configure the Philips Hue sample bundle +You will need a working `nodecg-io` installation. If you have non yet take a +look at [installation guide](../getting_started/install.md). You may need to +install this bundle, so take a look at the +[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide. It +will also tell you how to log in and how to use the GUI. -1. Start nodecg with nodecg-io installed. The philipshue-lights sample bundle is currently part of it, so it should also be loaded. +**You also need:** -2. Go to the `nodecg-io` tab in the nodecg dashboard. +- A Philips Hue bridge with some connected accessories -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. +### Configure the Philips Hue sample bundle -4. Create a new Philips Hue service instance using the left upper menu. +1. In NodeCG, create a new Philips Hue service instance. -5. Enter configuration for hue. +2. Enter configuration for hue. - The created instance should be automatically selected, if not select it in the upper left menu. If you want the bridge to be automatically discovered just set `discover` to true like this: + If you want the bridge to be automatically discovered just set `discover` to + true like this: ```json { @@ -27,7 +31,8 @@ The philipshue-lights example bundle in `samples/philipshue-lights` demonstrates } ``` - If you want to provide the IP address manually you can provide them like this: + If you want to provide the IP address manually you can provide them like + this: ```json { @@ -36,16 +41,17 @@ The philipshue-lights example bundle in `samples/philipshue-lights` demonstrates } ``` - After entering it, press the big link button on your bridge and then click save. - - After the first time you connect to your bridge it will create a user and an API key which will be saved so that you only need to press the link button when you connect it for the first time. - - _Note:_ If you don't see monaco on the right, try reloading the page. + After entering it, press the big link button on your bridge and then click + save. -6. Set the created Philips Hue service instance to the service dependency of the philipshue-lights sample bundle. + After the first time you connect to your bridge it will create a user and an + API key which will be saved so that you only need to press the link button + when you connect it for the first time. - Select the philipshue-lights sample bundle and the Philips Hue service in the left bottom menu and then select the service instance that should be used by the philipshue-lights sample bundle (in this case the name of the previously created Philips Hue instance). +3. Set the sample's (`philipshue-lights`) dependency to be the newly created + service instance (of type `philipshue`). -7. Check the nodecg logs +4. Check the NodeCG logs: - You should see an error or a success message and the number of lights that the bridge knows of. + You should see an error or a success message and the number of lights that + the bridge knows of. diff --git a/docs/samples/rcon.md b/docs/samples/rcon.md index 3f31fbfc..7946c06f 100644 --- a/docs/samples/rcon.md +++ b/docs/samples/rcon.md @@ -1,25 +1,26 @@ ## Using the RCON sample bundle -The rcon sample bundle in `samples/rcon-minecraft` shows how to send a command to a Minecraft server. +The rcon sample bundle in `samples/rcon-minecraft` shows how to send a command +to a Minecraft server. ### Prerequisites -- Working NodeCG & nodecg-io installation -- A working [Minecraft](https://minecraft.net) server. - -### Configure the rcon sample bundle +You will need a working `nodecg-io` installation. If you have non yet take a +look at [installation guide](../getting_started/install.md). You may need to +install this bundle, so take a look at the +[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide. It +will also tell you how to log in and how to use the GUI. -1. Start nodecg with nodecg-io installed. The rcon bundle is currently part of it, so it should also be loaded. +**You also need:** -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. +- A working [Minecraft](https://minecraft.net) server. -4. Create a new rcon service instance using the left upper menu. +### Configure the rcon sample bundle -5. Enter the host, port, and password of the rcon connection. This can be found in the `server.properties` file (`rcon.port`, `rcon.password`) +1. In NodeCG, create a new rcon service instance. - The created instance should be automatically selected, if not select it in the upper left menu. Enter your host and port in monaco (the text-editor on the right) in this format: +2. Enter the host, port, and password of the rcon connection. This can be found + in the `server.properties` file (`rcon.port`, `rcon.password`): ```json { @@ -31,6 +32,8 @@ The rcon sample bundle in `samples/rcon-minecraft` shows how to send a command t After entering it, click save. -6. Set the created rcon service instance to the service dependency of the rcon-minecraft bundle. +3. Set the sample's (`rcon-minecraft`) dependency to be the newly created + service instance (of type `rcon`). -7. In the nodecg console you will see a list with all online players. It will also send a /say command to the Minecraft server. +4. In the NodeCG console you will see a list with all online players. It will + also send a /say command to the Minecraft server. diff --git a/docs/samples/reddit.md b/docs/samples/reddit.md index 844a108d..08609f7c 100644 --- a/docs/samples/reddit.md +++ b/docs/samples/reddit.md @@ -1,27 +1,30 @@ ## Using the Reddit sample bundle -The reddit-message-read example bundle in `samples/reddit-msg-read` demonstrates the ability to read recent posts from a subreddit (in this case `r/skate702`) +The reddit-message-read example bundle in `samples/reddit-msg-read` demonstrates +the ability to read recent posts from a subreddit (in this case `r/skate702`) ### Prerequisites -- Working NodeCG & nodecg-io installation -- a Reddit Application (Should be of type script for own purpose) +You will need a working `nodecg-io` installation. If you have non yet take a +look at [installation guide](../getting_started/install.md). You may need to +install this bundle, so take a look at the +[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide. It +will also tell you how to log in and how to use the GUI. -_Note:_ If you don't have such an application yet, you can get one [here](https://www.reddit.com/prefs/apps). +**You also need:** -### Configure the Reddit sample bundle - -1. Start nodecg with nodecg-io installed. The reddit-message-read bundle is currently part of it, so it should also be loaded. - -2. Go to the `nodecg-io` tab in the nodecg dashboard. +- A Reddit Application (Should be of type script for own purpose) -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. +_Note:_ If you don't have such an application yet, you can get one +[here](https://www.reddit.com/prefs/apps). -4. Create a new Reddit service instance using the left upper menu. +### Configure the Reddit sample bundle -5. Enter your applications ID and secret and your own username and password. The entered username and password must be for the user who registered the application. +1. In NodeCG, create a new Reddit service instance. - The created instance should be automatically selected, if not select it in the upper left menu. Enter your data in monaco (the text-editor on the right) in this format: +2. Enter your applications ID and secret and your own username and password. The + entered username and password must be for the user who registered the + application: ```json { @@ -34,12 +37,9 @@ _Note:_ If you don't have such an application yet, you can get one [here](https: After entering it, click save. - _Note:_ If you don't see monaco on the right, try reloading the page. - -6. Set the created Reddit service instance to the service dependency of the reddit-message-read bundle. - - Select the reddit-message-read bundle and the Reddit service in the left bottom menu and then select the service instance that should be used by the reddit-message-read bundle (in this case the name of the previously created Reddit instance). +3. Set the sample's (`reddit-msg-read`) dependency to be the newly created + service instance (of type `reddit`). -7. Check the nodecg logs +4. Check the NodeCG logs: You should see the recent posts in `r/skate702` diff --git a/docs/samples/sacn-receiver.md b/docs/samples/sacn-receiver.md index 6b183912..849ae446 100644 --- a/docs/samples/sacn-receiver.md +++ b/docs/samples/sacn-receiver.md @@ -1,25 +1,25 @@ ## Using the sACN receiver sample bundle -The sacn-receiver-sample example bundle in `samples/sacn-receiver-sample` demonstrates the ability receive data send via sACN from e.g., professional lighting consoles. Here is a guide to how to get it working. +The sacn-receiver-sample example bundle in `samples/sacn-receiver-sample` +demonstrates the ability receive data send via sACN from e.g., professional +lighting consoles. Here is a guide to how to get it working. ### Prerequisites -- Working NodeCG & nodecg-io installation -- A working sACN sender in the current network - -### 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. - -2. Go to the `nodecg-io` tab in the nodecg dashboard. +You will need a working `nodecg-io` installation. If you have non yet take a +look at [installation guide](../getting_started/install.md). You may need to +install this bundle, so take a look at the +[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide. It +will also tell you how to log in and how to use the GUI. -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. +**You also need:** -4. Create a new sacn-receiver service instance using the left upper menu. +- A working sACN sender in the current network -5. Enter the needed options. +### Configure the sACN sample bundle - The created instance should be automatically selected, if not select it in the upper left menu. Enter your Bot token in monaco (the text-editor on the right) in this format: +1. In NodeCG, create a new sacn-receiver service instance. +2. Enter the needed options: **Universes** @@ -33,7 +33,8 @@ The sacn-receiver-sample example bundle in `samples/sacn-receiver-sample` demons **Port** - Optional. The multicast port to use. All professional consoles broadcast to the default port 5568. + Optional. The multicast port to use. All professional consoles broadcast to + the default port 5568. ```json { @@ -42,8 +43,9 @@ The sacn-receiver-sample example bundle in `samples/sacn-receiver-sample` demons } ``` - **Iface** - Optional. If the computer is connected to multiple networks, specify which network adaptor to use by using this computer's local IP address. + **Iface** Optional. If the computer is connected to multiple networks, + specify which network adaptor to use by using this computer's local IP + address. ```json { @@ -52,8 +54,8 @@ The sacn-receiver-sample example bundle in `samples/sacn-receiver-sample` demons } ``` - **ReuseAddr** - Optional. Allow multiple programs on your computer to listen to the same sACN universe. + **ReuseAddr** Optional. Allow multiple programs on your computer to listen + to the same sACN universe. ```json { @@ -64,12 +66,9 @@ The sacn-receiver-sample example bundle in `samples/sacn-receiver-sample` demons After entering them, click save. - _Note:_ If you don't see monaco on the right, try reloading the page. - -6. Set the created sacn-receiver service instance to the service dependency of the sacn-receiver-sample bundle. - - Select the sacn-receiver-sample bundle and the sacn-receiver service in the left bottom menu and then select the service instance that should be used by the sacn-receiver-sample bundle (in this case the name of the previously created sACN instance). +3. Set the sample's (`sacn-receiver-sample`) dependency to be the newly created + service instance (of type `sacn-receiver`). -7. Check the nodecg logs +4. Check the NodeCG logs: You should see data logged. diff --git a/docs/samples/sacn-sender.md b/docs/samples/sacn-sender.md index 3f985b4a..b0cc16b8 100644 --- a/docs/samples/sacn-sender.md +++ b/docs/samples/sacn-sender.md @@ -1,25 +1,25 @@ ## Using the sACN sender sample bundle -The sacn-sender example bundle in `samples/sacn-sender` demonstrates the ability send data via sACN to e.g., open lighting architecture or professional lighting equipment. Here is a guide to how to get it working. +The sacn-sender example bundle in `samples/sacn-sender` demonstrates the ability +send data via sACN to e.g., open lighting architecture or professional lighting +equipment. Here is a guide to how to get it working. ### Prerequisites -- Working NodeCG & nodecg-io installation -- A working sACN receiver in the current network - -### 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. - -2. Go to the `nodecg-io` tab in the nodecg dashboard. +You will need a working `nodecg-io` installation. If you have non yet take a +look at [installation guide](../getting_started/install.md). You may need to +install this bundle, so take a look at the +[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide. It +will also tell you how to log in and how to use the GUI. -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. +**You also need:** -4. Create a new sacn-sender service instance using the left upper menu. +- A working sACN receiver in the current network -5. Enter the needed options. +### Configure the sACN sample bundle - The created instance should be automatically selected, if not select it in the upper left menu. Enter your universe in monaco (the text-editor on the right) in this format: +1. In NodeCG, create a new sacn-sender service instance. +2. Enter the needed options: **Universes** @@ -33,7 +33,8 @@ The sacn-sender example bundle in `samples/sacn-sender` demonstrates the ability **Port** - Optional. The multicast port to use. All professional consoles broadcast to the default port 5568. + Optional. The multicast port to use. All professional consoles broadcast to + the default port 5568. ```json { @@ -42,8 +43,8 @@ The sacn-sender example bundle in `samples/sacn-sender` demonstrates the ability } ``` - **ReuseAddr** - Optional. Allow multiple programs on your computer to listen to the same sACN universe. + **ReuseAddr** Optional. Allow multiple programs on your computer to listen + to the same sACN universe. ```json { @@ -54,12 +55,9 @@ The sacn-sender example bundle in `samples/sacn-sender` demonstrates the ability After entering them, click save. - _Note:_ If you don't see monaco on the right, try reloading the page. - -6. Set the created sacn-sender service instance to the service dependency of the sacn-sender bundle. - - Select the sacn-sender bundle and the sacn-sender service in the left bottom menu and then select the service instance that should be used by the sacn-sender bundle (in this case the name of the previously created sACN instance). +3. Set the sample's (`sacn-sender`) dependency to be the newly created service + instance (of type `sacn-sender`). -7. Check the nodecg logs +4. Check the NodeCG logs: You should see data logged. diff --git a/docs/samples/serial.md b/docs/samples/serial.md index 2f25d6db..67965d3f 100644 --- a/docs/samples/serial.md +++ b/docs/samples/serial.md @@ -1,27 +1,27 @@ ## Using the serial sample bundle -The serial example bundle in `samples/serial` demonstrates the ability to exchange data with a device that is connected via serial. Here is a guide to how to get it working. +The serial example bundle in `samples/serial` demonstrates the ability to +exchange data with a device that is connected via serial. Here is a guide to how +to get it working. ### Prerequisites -- Working NodeCG & nodecg-io installation -- An Arduino or any other microcontroller development board that can send and receive data via serial. +You will need a working `nodecg-io` installation. If you have non yet take a +look at [installation guide](../getting_started/install.md). You may need to +install this bundle, so take a look at the +[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide. It +will also tell you how to log in and how to use the GUI. -### Configure the serial sample bundle - -1. Load a simple serial echo sketch on your microcontroller. You can find a working Arduino sketch at the end of this article. - -2. Start nodecg with nodecg-io installed. The serial bundle is currently part of it, so it should also be loaded. Make sure the device is already connected. Otherwise, you won't be able to see the device. +**You also need:** -3. Go to the `nodecg-io` tab in the nodecg dashboard. +- An Arduino or any other microcontroller development board that can send and + receive data via serial. -4. Login using your password. If this is your first run, then enter the password with which you want to encrypt your configurations and credentials. - -5. Create a new serial service instance using the left upper menu. +### Configure the serial sample bundle -6. Enter the information of your device. +1. In NodeCG, create a new serial service instance. - The created instance should be automatically selected, if not select it in the upper left menu. Enter the `com port` or other identifying information in one of these formats: +2. Enter the information of your device: ```json { @@ -41,19 +41,23 @@ The serial example bundle in `samples/serial` demonstrates the ability to exchan After entering it, click save. - _Note:_ If you don't see monaco on the right, try reloading the page. - _Note:_ If you want to list all connected devices you can open a terminal in `nodecg-io-serial` and run `npm run list`. - _Note:_ If you are using multiple devices you might want to use the `pnpId`, since ports can change between reboots! - -7. Set the created serial service instance to the service dependency of the serial bundle. + _Note:_ If you want to list all connected devices you can open a terminal in + `nodecg-io-serial` and run `npm run list`. _Note:_ If you are using multiple + devices you might want to use the `pnpId`, since ports can change between + reboots! - Select the serial bundle and the serial service in the left bottom menu and then select the service instance that should be used by the serial bundle (in this case the name of the previously created serial instance). +3. Set the sample's (`serial`) dependency to be the newly created service + instance (of type `serial`). -8. Check the nodecg logs +4. Check the NodeCG logs: - You should see an error or a success message and nodecg-io will send ping to the microcontroller every 10 seconds. The Arduino device will respond with pong. You should see the pong message displayed in the log. + You should see an error or a success message and nodecg-io will send ping to + the microcontroller every 10 seconds. The Arduino device will respond with + pong. You should see the pong message displayed in the log. - If you see an error or nothing at all, try making sure your microcontroller is plugged in and recognized correctly. Then restart nodecg, so the service is cleanly restarted. + If you see an error or nothing at all, try making sure your microcontroller + is plugged in and recognized correctly. Then restart NodeCG, so the service + is cleanly restarted. ### Sample Arduino sketch diff --git a/docs/samples/shlink.md b/docs/samples/shlink.md index 83bff69d..6adf7def 100644 --- a/docs/samples/shlink.md +++ b/docs/samples/shlink.md @@ -1,25 +1,26 @@ ## Using the Shlink sample bundle -The Shlink example bundle in `samples/shlink-list-short-urls` demonstrates the ability to control a [Shlink](https://shlink.io/) server by getting the amount of short urls configured on the server. Here is a guide on how to get it working. +The Shlink example bundle in `samples/shlink-list-short-urls` demonstrates the +ability to control a [Shlink](https://shlink.io/) server by getting the amount +of short URLs configured on the server. Here is a guide on how to get it +working. ### Prerequisites -- Working NodeCG & nodecg-io installation -- [Shlink server and valid API key / token for it](https://shlink.io/documentation/install-docker-image/) - -### Configure the Shlink sample bundle - -1. Start nodecg with nodecg-io installed. The shlink-list-short-urls bundle is currently part of it so it should also be loaded. - -2. Go to the `nodecg-io` tab in the nodecg dashboard. +You will need a working `nodecg-io` installation. If you have non yet take a +look at [installation guide](../getting_started/install.md). You may need to +install this bundle, so take a look at the +[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide. It +will also tell you how to log in and how to use the GUI. -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. +**You also need:** -4. Create a new Shlink service instance using the left upper menu. +- [Shlink server and valid API key / token for it](https://shlink.io/documentation/install-docker-image/) -5. Enter the configuration for Shlink. +### Configure the Shlink sample bundle - The created instance should be automatically selected, if not, select it in the upper left menu. Enter the connection information for the Shlink server in monaco (the text-editor on the right) in this format: +1. In NodeCG, create a new Shlink service instance. +2. Enter the configuration for Shlink: ```json { @@ -30,14 +31,14 @@ The Shlink example bundle in `samples/shlink-list-short-urls` demonstrates the a After entering it, click save. - _Note:_ If you don't see monaco on the right, try reloading the page. - -6. Set the created Shlink service instance to the service dependency of the shlink-list-short-urls bundle. - - Select the shlink-list-short-urls bundle and the Shlink service in the left bottom menu and then select the service instance that should be used by the shlink-list-short-urls bundle (in this case the name of the previously created Shlink instance). +3. Set the sample's (`shlink-list-short-urls`) dependency to be the newly + created service instance (of type `shlink`). -7. Check the nodecg logs +4. Check the NodeCG logs: - You should see an error or a success message and the amount of configured short urls on the Shlink server. + You should see an error or a success message and the amount of configured + short URLs on the Shlink server. - _Note:_ When listing short urls - like this sample does - be aware that the amount of short urls might be limited by the [API key role](https://shlink.io/documentation/api-docs/api-key-roles/). + _Note:_ When listing short URLs — like this sample does — be aware that the + amount of short URLs might be limited by the + [API key role](https://shlink.io/documentation/api-docs/api-key-roles/). diff --git a/docs/samples/slack.md b/docs/samples/slack.md index 283f5cba..6574de51 100644 --- a/docs/samples/slack.md +++ b/docs/samples/slack.md @@ -1,27 +1,29 @@ ## Using the Slack sample bundle -The Slack example bundle in `samples/slack-post` demonstrates the ability to list all channels into the console and sends a message to a channel which you have to configure to your channel ID. +The Slack example bundle in `samples/slack-post` demonstrates the ability to +list all channels into the console and sends a message to a channel which you +have to configure to your channel ID. ### Prerequisites -- Working NodeCG & nodecg-io installation -- a Slack Bot token - -_Note:_ If you don't have such a token yet, you can create your own app with token on [this](https://app.slack.com/apps-manage/) page. - -### Configure the Slack sample bundle +You will need a working `nodecg-io` installation. If you have non yet take a +look at [installation guide](../getting_started/install.md). You may need to +install this bundle, so take a look at the +[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide. It +will also tell you how to log in and how to use the GUI. -1. Start nodecg with nodecg-io installed. The slack bundle is currently part of it, so it should also be loaded. +**You also need:** -2. Go to the `nodecg-io` tab in the nodecg dashboard. +- a Slack Bot token -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. +_Note:_ If you don't have such a token yet, you can create your own app with +token on [this](https://app.slack.com/apps-manage/) page. -4. Create a new slack service instance using the left upper menu. +### Configure the Slack sample bundle -5. Enter your Slack app token. +1. In NodeCG, create a new slack service instance. - The created instance should be automatically selected, if not select it in the upper left menu. Enter your token in monaco (the text-editor on the right) in this format: +2. Enter your Slack app token: ```json { @@ -31,12 +33,9 @@ _Note:_ If you don't have such a token yet, you can create your own app with tok After entering it, click save. - _Note:_ If you don't see monaco on the right, try reloading the page. - -6. Set the created slack service instance to the service dependency of the slack bundle. - - Select the slack bundle and the slack service in the left bottom menu and then select the service instance that should be used by the slack bundle (in this case the name of the previously created slack instance). +3. Set the sample's (`slack-post`) dependency to be the newly created service + instance (of type `slack`). -7. Check the nodecg logs +4. Check the NodeCG logs: You should see an error or a login message. diff --git a/docs/samples/spotify.md b/docs/samples/spotify.md index 934eb6f8..04ae1d8c 100644 --- a/docs/samples/spotify.md +++ b/docs/samples/spotify.md @@ -1,27 +1,31 @@ ## Using the Spotify sample bundle -The spotify-current-song example bundle in `samples/spotify-current-song` demonstrates the ability to get the current playing song of a user. Here is a guide to how to get it working. +The spotify-current-song example bundle in `samples/spotify-current-song` +demonstrates the ability to get the current playing song of a user. Here is a +guide to how to get it working. ### Prerequisites -- Working NodeCG & nodecg-io installation -- A Spotify account and a registered Spotify application and the associated client id/client secret. +You will need a working `nodecg-io` installation. If you have non yet take a +look at [installation guide](../getting_started/install.md). You may need to +install this bundle, so take a look at the +[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide. It +will also tell you how to log in and how to use the GUI. -_Note:_ If you don't have a registered application, yet you can follow [this guide](https://developer.spotify.com/documentation/general/guides/app-settings/#register-your-app). As a redirect URL use . +**You also need:** -### Configure the Spotify sample bundle - -1. Start nodecg with nodecg-io installed. The spotify-current-song bundle is currently part of it, so it should also be loaded. - -2. Go to the `nodecg-io` tab in the nodecg dashboard. +- A Spotify account and a registered Spotify application and the associated + client id/client secret. -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. +_Note:_ If you don't have a registered application, yet you can follow +[this guide](https://developer.spotify.com/documentation/general/guides/app-settings/#register-your-app). +As a redirect URL use . -4. Create a new Spotify service instance using the left upper menu. +### Configure the Spotify sample bundle -5. Enter credentials for Spotify. +1. In NodeCG, create a new Spotify service instance. - The created instance should be automatically selected, if not select it in the upper left menu. Enter your client ID and secret in monaco (the text-editor on the right) in this format: +2. Enter your client ID and secret for Spotify: ```json { @@ -33,14 +37,15 @@ _Note:_ If you don't have a registered application, yet you can follow [this gui After entering it, click save. - _Note:_ If you don't see monaco on the right, try reloading the page. - _Note:_ This sample requires the `user-read-playback-state` scope, but you can require other scopes if you want to use functions that require them. - A list of all scopes can be found [here](https://developer.spotify.com/documentation/general/guides/scopes/). - -6. Set the created Spotify service instance to the service dependency of the spotify-current-song bundle. + _Note:_ This sample requires the `user-read-playback-state` scope, but you + can require other scopes if you want to use functions that require them. A + list of all scopes can be found + [here](https://developer.spotify.com/documentation/general/guides/scopes/). - Select the spotify-current-song bundle and the Spotify service in the left bottom menu and then select the service instance that should be used by the spotify-current-song bundle (in this case the name of the previously created Spotify instance). +3. Set the sample's (`spotify-current-song`) dependency to be the newly created + service instance (of type `spotify`). -7. Check the nodecg logs +4. Check the NodeCG logs: - You should see an error or a success message and the current playing song with names and artists. + You should see an error or a success message and the current playing song + with names and artists. diff --git a/docs/samples/sql.md b/docs/samples/sql.md index be0c9074..be69b54b 100644 --- a/docs/samples/sql.md +++ b/docs/samples/sql.md @@ -1,27 +1,30 @@ ## Using the SQL sample bundle -The SQL example bundle in `samples/sql` demonstrates the ability to access databases. Here is a guide to how to get it working. +The SQL example bundle in `samples/sql` demonstrates the ability to access +databases. Here is a guide to how to get it working. ### Prerequisites -- Working NodeCG & nodecg-io installation -- A database supported by [knex](https://knexjs.org/#Installation) - -_Note:_ If you don't have a database yet and just want to test things you can use sqlite3 and don't need to set up a database server. You can always move to a different database type later. - -### Configure the SQL sample bundle +You will need a working `nodecg-io` installation. If you have non yet take a +look at [installation guide](../getting_started/install.md). You may need to +install this bundle, so take a look at the +[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide. It +will also tell you how to log in and how to use the GUI. -1. Start nodecg with nodecg-io installed. The SQL sample bundle is currently part of it, so it should also be loaded. +**You also need:** -2. Go to the `nodecg-io` tab in the nodecg dashboard. +- A database supported by [knex](https://knexjs.org/#Installation) -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. +_Note:_ If you don't have a database yet and just want to test things you can +use sqlite3 and don't need to set up a database server. You can always move to a +different database type later. -4. Create a new SQL service instance using the left upper menu. +### Configure the SQL sample bundle -5. Enter configuration for SQL. +1. In NodeCG, create a new SQL service instance. - The created instance should be automatically selected, if not select it in the upper left menu. Enter your used database client and a [knex connection object](https://knexjs.org/#Installation-client) in monaco (the text-editor on the right) in this format: +2. Enter your used database client and a + [knex connection object](https://knexjs.org/#Installation-client) for SQL: ```json { @@ -35,14 +38,13 @@ _Note:_ If you don't have a database yet and just want to test things you can us After entering it, click save. - _Note:_ If you don't see monaco on the right, try reloading the page. - -6. Set the created SQL service instance to the service dependency of the SQL sample bundle. - - Select the SQL sample bundle and the SQL service in the left bottom menu and then select the service instance that should be used by the SQL sample bundle (in this case the name of the previously created SQL instance). +3. Set the sample's (`sql`) dependency to be the newly created service instance + (of type `sql`). -7. Check the nodecg logs +4. Check the NodeCG logs: - Your first run of the sample bundle will probably fail because your database doesn't contain the used tables. - Check `samples/sql/extension/index.ts` and create the tables as used or create your own tables and adapt the sample accordingly. - You can also use this code as a reference on how to use the SQL client to do your queries. + Your first run of the sample bundle will probably fail because your database + doesn't contain the used tables. Check `samples/sql/extension/index.ts` and + create the tables as used or create your own tables and adapt the sample + accordingly. You can also use this code as a reference on how to use the SQL + client to do your queries. diff --git a/docs/samples/streamdeck.md b/docs/samples/streamdeck.md index 94d1c2d9..92643d25 100644 --- a/docs/samples/streamdeck.md +++ b/docs/samples/streamdeck.md @@ -1,22 +1,30 @@ ## Using the StreamDeck rainbow sample bundle -The streamdeck-rainbow bundle paints your streamdeck with different colours. It is located in `samples/streamdeck-rainbow`. +The streamdeck-rainbow bundle paints your streamdeck with different colours. It +is located in `samples/streamdeck-rainbow`. -Sadly you can't access the StreamDeck while another application accesses it. So you need to stop your StreamDeck Software before. +Sadly you can't access the StreamDeck while another application accesses it. So +you need to stop your StreamDeck Software before. -### Configure the Streamdeck Rainbow bundle +### Prerequisites -1. If you're on Linux, follow the instructions listed under Manual Installation [here](https://github.com/timothycrosley/streamdeck-ui/blob/master/README.md). Everything after the `sudo udevadm` command can be omitted. +You will need a working `nodecg-io` installation. If you have non yet take a +look at [installation guide](../getting_started/install.md). You may need to +install this bundle, so take a look at the +[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide. It +will also tell you how to log in and how to use the GUI. -2. Start nodecg with nodecg-io installed. The streamdeck-rainbow bundle is currently part of it, so it should also be loaded. +**You also need:** (If you're on Linux) -3. Go to the `nodecg-io` tab in the nodecg dashboard. +Follow the instructions listed under Manual Installation +[here](https://github.com/timothycrosley/streamdeck-ui/blob/master/README.md). +Everything after the `sudo udevadm` command can be omitted. -4. Login using your password. If this is your first run, then enter the password with which you want to encrypt your configurations and credentials. +### Configure the Streamdeck Rainbow bundle -5. Create a new StreamDeck service instance using the left upper menu. +1. In NodeCG, create a new StreamDeck service instance. -6. Enter the configuration +2. Enter the configuration: ```json { @@ -24,8 +32,10 @@ Sadly you can't access the StreamDeck while another application accesses it. So } ``` - `default` tells the bundle to automatically find a StreamDeck. If you use multiple StreamDecks, you need to put in an ID here. + `default` tells the bundle to automatically find a StreamDeck. If you use + multiple StreamDecks, you need to put in an ID here. -7. Set the created StreamDeck service instance to the service dependency of the streamdeck-rainbow bundle. +3. Set the sample's (`streamdeck-rainbow`) dependency to be the newly created + service instance (of type `streamdeck`). -8. Watch your streamdeck. +4. Watch your streamdeck. diff --git a/docs/samples/streamelements.md b/docs/samples/streamelements.md index 8c5d7dc5..fc0c7455 100644 --- a/docs/samples/streamelements.md +++ b/docs/samples/streamelements.md @@ -1,31 +1,34 @@ ## Using the StreamElements sample bundle -The StreamElements-events example bundle in `samples/streamelements-events` demonstrates the ability to react to events like donations and subs. Here is a guide to how to get it working. +The StreamElements-events example bundle in `samples/streamelements-events` +demonstrates the ability to react to events like donations and subs. Here is a +guide to how to get it working. ### Prerequisites -- Working NodeCG & nodecg-io installation +You will need a working `nodecg-io` installation. If you have non yet take a +look at [installation guide](../getting_started/install.md). You may need to +install this bundle, so take a look at the +[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide. It +will also tell you how to log in and how to use the GUI. + +**You also need:** + - A StreamElements account ### Getting JWT Token -To use the StreamElements service you need a JWT Token that gives it access to your account. +To use the StreamElements service you need a JWT Token that gives it access to +your account. -To get it go to , login, click on `Show Secrets` and copy it. +To get it go to , login, +click on `Show Secrets` and copy it. ### Configure the StreamElements sample bundle -1. Start nodecg with nodecg-io installed. The streamelements-events 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. +1. In NodeCG, create a new StreamElements service instance. -4. Create a new StreamElements service instance using the left upper menu. - -5. Enter credentials for StreamElements. - - The created instance should be automatically selected, if not select it in the upper left menu. Enter your JWT Token in monaco (the text-editor on the right) in this format: +2. Enter the JWT Token for StreamElements: ```json { @@ -35,12 +38,10 @@ To get it go to , login, After entering it, click save. - _Note:_ If you don't see monaco on the right, try reloading the page. - -6. Set the created StreamElements service instance to the service dependency of the streamelements-events bundle. - - Select the streamelements-events bundle and the StreamElements service in the left bottom menu and then select the service instance that should be used by the streamelements-events bundle (in this case the name of the previously created streamelements-events instance). +3. Set the sample's (`streamelements-events`) dependency to be the newly created + service instance (of type `streamelements`). -7. Check the nodecg logs +4. Check the NodeCG logs: - You should see an error or a success message and a log message for each event of your channel like subs, follows, cheers, raids and so on. + You should see an error or a success message and a log message for each + event of your channel like subs, follows, cheers, raids and so on. diff --git a/docs/samples/telegram.md b/docs/samples/telegram.md index f067e443..17d432f9 100644 --- a/docs/samples/telegram.md +++ b/docs/samples/telegram.md @@ -1,25 +1,26 @@ ## Using the telegram sample bundle -The telegram sample bundle in `samples/telegram-bot` shows how to create a simple command. +The telegram sample bundle in `samples/telegram-bot` shows how to create a +simple command. ### Prerequisites -- Working NodeCG & nodecg-io installation -- A telegram bot API token. You can create your bot [here](https://t.me/botfather). +You will need a working `nodecg-io` installation. If you have non yet take a +look at [installation guide](../getting_started/install.md). You may need to +install this bundle, so take a look at the +[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide. It +will also tell you how to log in and how to use the GUI. -### Configure the telegram sample bundle - -1. Start nodecg with nodecg-io installed. The telegram bundle is currently part of it, so it should also be loaded. +**You also need:** -2. Go to the `nodecg-io` tab in the nodecg dashboard. +- A telegram-bot API token. You can create your bot + [here](https://t.me/botfather). -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 telegram service instance using the left upper menu. +### Configure the telegram sample bundle -5. Enter the token and set polling to true. +1. Create a new telegram service instance. - The created instance should be automatically selected, if not select it in the upper left menu. Enter your host and port in monaco (the text-editor on the right) in this format: +2. Enter the token and set polling to true: ```json { @@ -30,6 +31,7 @@ The telegram sample bundle in `samples/telegram-bot` shows how to create a simpl After entering it, click save. -6. Set the created telegram service instance to the service dependency of the telegram bundle. +3. Set the sample's (`telegram-bot`) dependency to be the newly created service + instance (of type `telegram`). -7. You can send `/test` to your bot, and it should respond with two messages. +4. You can send `/test` to your bot, and it should respond with two messages. diff --git a/docs/samples/tiane.md b/docs/samples/tiane.md index 9e544530..96ed6233 100644 --- a/docs/samples/tiane.md +++ b/docs/samples/tiane.md @@ -1,22 +1,39 @@ ## Using the TIANE-Discord sample bundle -The TIANE-Discord example bundle in `samples/tiane-discord` shows how to make TIANE act as a discord bot. TIANE is a German open source smart home assistant written in python. Here is a guide to how to get it working. +The TIANE-Discord example bundle in `samples/tiane-discord` shows how to make +TIANE act as a discord bot. TIANE is a German open source smart home assistant +written in python. Here is a guide to how to get it working. ### Prerequisites -- Working NodeCG & nodecg-io installation -- A working [TIANE](https://github.com/FerdiKr/TIANE) server installation. (No room client required) +You will need a working `nodecg-io` installation. If you have non yet take a +look at [installation guide](../getting_started/install.md). You may need to +install this bundle, so take a look at the +[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide. It +will also tell you how to log in and how to use the GUI. + +**You also need:** + +- A working [TIANE](https://github.com/FerdiKr/TIANE) server installation. (No + room client required) - a Discord Bot token +_Note:_ If you don't Discord Bot token yet, you can follow +[this](https://discordjs.guide/preparations/setting-up-a-bot-application.html) +guide. + ### Configure the TIANE sample bundle 1. Edit the file `samples/tiane-discord/extension/index.ts`. Look for this line: - ``` + ```ts const discordChannel = ""; // Insert channel for the discord bot here ``` - Put the channel ID of a discord channel where you want to talk to TIANE between the quotation marks. See [here](https://github.com/Chikachi/DiscordIntegration/wiki/How-to-get-a-token-and-channel-ID-for-Discord) to find out how to get a channel ID. + Put the channel ID of a discord channel where you want to talk to TIANE + between the quotation marks. See + [here](https://github.com/Chikachi/DiscordIntegration/wiki/How-to-get-a-token-and-channel-ID-for-Discord) + to find out how to get a channel ID. 2. Run `npm run build` in the main nodecg-io directory. 3. Edit the file `server/TIANE_config.json` on your TIANE server: @@ -29,19 +46,13 @@ The TIANE-Discord example bundle in `samples/tiane-discord` shows how to make TI } ``` - Make sure `websocket` is either set to `enabled` or `secure` and set a port of your desire. - -4. Start nodecg with nodecg-io installed. The TIANE-Discord bundle is currently part of it, so it should also be loaded. + Make sure `websocket` is either set to `enabled` or `secure` and set a port + of your desire. -5. Go to the `nodecg-io` tab in the nodecg dashboard. +4. In the NodeCG dashboard, create a new TIANE service instance. -6. Login using your password. If this is your first run, then enter the password with which you want to encrypt your configurations and credentials. - -7. Create a new TIANE service instance using the left upper menu. - -8. Enter address of the TIANE-Server - - The created instance should be automatically selected, if not select it in the upper left menu. Enter host and port you just set in `server/TIANE_config.json` in this format: +5. Enter address of the TIANE-Server. Enter host and port you just set in + `server/TIANE_config.json` in this format: ```json { @@ -51,12 +62,10 @@ The TIANE-Discord example bundle in `samples/tiane-discord` shows how to make TI After entering it, click save. - _Note:_ If you don't see the editor on the right, try reloading the page. - -9. Create a new Discord service instance. (See the [Discord Sample](discord.md) on how to do this) - -10. Set the created TIANE and Discord service instances to the service dependency of the TIANE-Discord bundle. +6. Create a new Discord service instance. - Select the TIANE-Discord bundle and the TIANE service in the left bottom menu and then select the service instance that should be used by the TIANE-Discord bundle (in this case the name of the previously created twitch instance). Then do the same for the discord bundle. +7. Set the sample's (`tiane-discord`) dependencies to be the newly created + service instances (of type `tiane` & `discord`). -11. Ping your discord bot in the channel you set in the first step and ask TIANE something. +8. Ping your discord bot in the channel you set in the first step and ask TIANE + something. diff --git a/docs/samples/twitch-addons.md b/docs/samples/twitch-addons.md index 920c6014..cc120db7 100644 --- a/docs/samples/twitch-addons.md +++ b/docs/samples/twitch-addons.md @@ -1,27 +1,31 @@ ## Using the Twitch-Addons sample bundle -The Twitch-Addons example bundle in `samples/twitch-addons` demonstrates the ability to send requests to the APIs of [BetterTTV](https://betterttv.com/), and [FrankerFaceZ](https://www.frankerfacez.com/). +The Twitch-Addons example bundle in `samples/twitch-addons` demonstrates the +ability to send requests to the APIs of [BetterTTV](https://betterttv.com/), and +[FrankerFaceZ](https://www.frankerfacez.com/). ### Prerequisites -- Working NodeCG & nodecg-io installation -- a Twitch OAuth Key +You will need a working `nodecg-io` installation. If you have non yet take a +look at [installation guide](../getting_started/install.md). You may need to +install this bundle, so take a look at the +[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide. It +will also tell you how to log in and how to use the GUI. -_Note:_ If you don't have such a key yet, you can generate it on . Just log into your Twitch account and copy the token. You can also use any other token. There are no special scope requirements as the token is only used to convert channel names to IDs. +**You also need:** -### Configure the Twitch-Addons sample bundle - -1. Start nodecg with nodecg-io installed. The Twitch-Addons bundle is currently part of it, so it should also be loaded. - -2. Go to the `nodecg-io` tab in the nodecg dashboard. +- A Twitch oAuth-Key -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. +_Note:_ If you don't have such a key yet, you can generate it on +. Just log into your Twitch account and copy the +token. You can also use any other token. There are no special scope requirements +as the token is only used to convert channel names to IDs. -4. Create a new twitch-addons service instance using the left upper menu. +### Configure the Twitch-Addons sample bundle -5. Enter credentials for twitch. +1. In NodeCG, create a new twitch-addons service instance. - The created instance should be automatically selected, if not select it in the upper left menu. Enter your Twitch OAuth Key in monaco (the text-editor on the right) in this format: +2. Enter your Twitch OAuth Key: ```json { @@ -31,12 +35,10 @@ _Note:_ If you don't have such a key yet, you can generate it on , select custom scope token and select the scopes you need. For this sample you don't need any additional scopes, so you can leave everything off. +**You also need:** -### Configure the Twitch API sample bundle - -1. Start nodecg with nodecg-io installed. The twitch-api bundle is currently part of it, so it should also be loaded. - -2. Go to the `nodecg-io` tab in the nodecg dashboard. +- A Twitch oAuth-Key -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. +_Note:_ If you don't have such a key yet, you can generate it on +, select custom scope token and select the +scopes you need. For this sample you don't need any additional scopes, so you +can leave everything off. -4. Create a new twitch-api service instance using the left upper menu. +### Configure the Twitch API sample bundle -5. Enter credentials for the twitch API. +1. In NodeCG, create a new twitch-api service instance. - The created instance should be automatically selected, if not select it in the upper left menu. Enter your Twitch OAuth Key in monaco (the text-editor on the right) in this format: +2. Enter your Twitch OAuth Key: ```json { @@ -31,12 +35,10 @@ _Note:_ If you don't have such a key yet, you can generate it on . Just log into your Twitch account and copy the token. - -### Configure the Twitch sample bundle +You will need a working `nodecg-io` installation. If you have non yet take a +look at [installation guide](../getting_started/install.md). You may need to +install this bundle, so take a look at the +[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide. It +will also tell you how to log in and how to use the GUI. -1. Start nodecg with nodecg-io installed. The Twitch-chat bundle is currently part of it, so it should also be loaded. +**You also need:** -2. Go to the `nodecg-io` tab in the nodecg dashboard. +- a Twitch oAuth-Key -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. +_Note:_ If you don't have such a key yet, you can generate it on +. Just log into your Twitch account and copy the +token. -4. Create a new twitch-chat service instance using the left upper menu. +### Configure the Twitch sample bundle -5. Enter credentials for twitch. +1. In NodeCG, create a new twitch-chat service instance. - The created instance should be automatically selected, if not select it in the upper left menu. Enter your Twitch OAuth Key in monaco (the text-editor on the right) in this format: +2. Enter your Twitch OAuth Key: ```json { @@ -31,12 +34,11 @@ _Note:_ If you don't have such a key yet, you can generate it on , select custom scope token and select these scopes: `channel_subscriptions`, `bits:read` and `channel:read:redemptions` +**You also need:** -### Configure the Twitch PubSub sample bundle - -1. Start nodecg with nodecg-io installed. The twitch-pubsub sample bundle is currently part of it, so it should also be loaded. - -2. Go to the `nodecg-io` tab in the nodecg dashboard. +- A Twitch oAuth-Key -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. +_Note:_ If you don't have such a key yet, you can generate it on +, select custom scope token and select these +scopes: `channel_subscriptions`, `bits:read` and `channel:read:redemptions` -4. Create a new twitch-pubsub service instance using the left upper menu. +### Configure the Twitch PubSub sample bundle -5. Enter credentials for twitch-pubsub. +1. In NodeCG, create a new twitch-pubsub service instance. - The created instance should be automatically selected, if not select it in the upper left menu. Enter your Twitch OAuth Key in monaco (the text-editor on the right) in this format: +2. Enter your Twitch OAuth Key: ```json { @@ -31,12 +33,10 @@ _Note:_ If you don't have such a key yet, you can generate it on ) to get the necessary keys and tokens. +_Note:_ You will need a Twitter developer account +() to get the necessary keys +and tokens. ### Configure the sample bundle -1. Start nodecg with nodecg-io installed. The twitter-timeline 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. +1. In NodeCG, create a new twitter service instance. -4. Create a new twitter service instance using the left upper menu. - -5. Enter credentials for twitter. - - The created instance should be automatically selected, if not select it in the upper left menu. Enter your Twitter keys and tokens in monaco (the text-editor on the right) in this format: +2. Enter your Twitter keys and tokens: ```json { @@ -38,21 +41,23 @@ _Note:_ You will need a Twitter developer account (", params, callback) diff --git a/docs/samples/websocket-client.md b/docs/samples/websocket-client.md index ca962e18..c6e9d13b 100644 --- a/docs/samples/websocket-client.md +++ b/docs/samples/websocket-client.md @@ -1,28 +1,27 @@ ## Using the WebSocket-client sample bundle -The WebSocket-client sample bundle in `samples/websocket-client` shows how to set up a simple WebSocket client that will ping a server every second. +The WebSocket-client sample bundle in `samples/websocket-client` shows how to +set up a simple WebSocket client that will ping a server every second. ### Prerequisites -- Working NodeCG & nodecg-io installation +You will need a working `nodecg-io` installation. If you have non yet take a +look at [installation guide](../getting_started/install.md). You may need to +install this bundle, so take a look at the +[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide. It +will also tell you how to log in and how to use the GUI. For simplicity's sake this sample will rely upon the websocket-server sample. ### Configure the WebSocket-client sample bundle -Please set up the WebSocket-server bundle first and then follow these steps: +Please set up the [WebSocket-server bundle](./websocket-server.md) first and +then follow these steps: -1. Start nodecg with nodecg-io installed. The websocket-client bundle is currently part of it, so it should also be loaded. +1. In NodeCG, create a new ws-client service instance. -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 ws-client service instance using the left upper menu. - -5. Enter the address of the sample server. This has to be a URL following the pattern `ws://localhost:`. - - The created instance should be automatically selected, if not select it in the upper left menu. Enter your port in monaco (the text-editor on the right) in this format: +2. Enter the address of the sample server. This has to be a URL following the + pattern `ws://localhost:`. ```json { @@ -32,6 +31,8 @@ Please set up the WebSocket-server bundle first and then follow these steps: After entering it, click save. -6. Set the created ws-client service instance to the service dependency of the ws-client bundle. +3. Set the sample's (`websocket-client`) dependency to be the newly created + service instance (of type `websocket-client`). -7. A websocket-client has been connected and the console should display if a ping is sent or a pong is received. +4. A websocket-client has been connected and the console should display if a + ping is sent or a pong is received. diff --git a/docs/samples/websocket-server.md b/docs/samples/websocket-server.md index 74346c8e..9cb8ec86 100644 --- a/docs/samples/websocket-server.md +++ b/docs/samples/websocket-server.md @@ -1,24 +1,21 @@ ## Using the WebSocket Server sample bundle -The WebSocket-server sample bundle in `samples/websocket-server` shows how to set up a simple WebSocket server that will relay all incoming messages to all connected clients. +The WebSocket-server sample bundle in `samples/websocket-server` shows how to +set up a simple WebSocket server that will relay all incoming messages to all +connected clients. ### Prerequisites -- Working NodeCG & nodecg-io installation +You will need a working `nodecg-io` installation. If you have non yet take a +look at [installation guide](../getting_started/install.md). You may need to +install this bundle, so take a look at the +[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide. It +will also tell you how to log in and how to use the GUI. ### Configure the websocket-server sample bundle -1. Start nodecg with nodecg-io installed. The websocket-server 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 ws-server service instance using the left upper menu. - -5. Enter a port for the server. This has to be a number from 0 to 65535. - - The created instance should be automatically selected, if not select it in the upper left menu. Enter your port in monaco (the text-editor on the right) in this format: +1. In NodeCG, create a new ws-server service instance. +2. Enter a port for the server. This has to be a number from 0 to 65535: ```json { @@ -28,6 +25,7 @@ The WebSocket-server sample bundle in `samples/websocket-server` shows how to se After entering it, click save. -6. Set the created ws-server service instance to the service dependency of the ws-server bundle. +3. Set the sample's (`websocket-server`) dependency to be the newly created + service instance (of type `websocket-server`). -7. A websocket-server has been started at the specified port. +4. A websocket-server has been started at the specified port. diff --git a/docs/samples/xdotool.md b/docs/samples/xdotool.md index 486d26be..2c53afb9 100644 --- a/docs/samples/xdotool.md +++ b/docs/samples/xdotool.md @@ -1,25 +1,25 @@ ## Using the Xdotool sample bundle -The Xdotool sample bundle in `samples/xdotool-windowminimize` shows how to use the xdotool service to execute [xdotool commands](http://manpages.ubuntu.com/manpages/trusty/man1/xdotool.1.html) by minimizing the currently active window. +The Xdotool sample bundle in `samples/xdotool-windowminimize` shows how to use +the xdotool service to execute +[xdotool commands](http://manpages.ubuntu.com/manpages/trusty/man1/xdotool.1.html) +by minimizing the currently active window. ### Prerequisites -- Working NodeCG & nodecg-io installation -- xdotool installed (Only works on Linux) +You will need a working `nodecg-io` installation. If you have non yet take a +look at [installation guide](../getting_started/install.md). You may need to +install this bundle, so take a look at the +[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide. It +will also tell you how to log in and how to use the GUI. -### Configure the Xdotool sample bundle - -1. Start nodecg with nodecg-io installed. The xdotool bundle is currently part of it, so it should also be loaded. - -2. Go to the `nodecg-io` tab in the nodecg dashboard. +- Xdotool installed (Only works on Linux) -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 xdotool service instance using the left upper menu. +### Configure the Xdotool sample bundle -5. Enter settings port `-1` tells nodecg-io to use a locally installed xdotool. +1. In NodeCG, create a new xdotool service instance. - The created instance should be automatically selected, if not select it in the upper left menu. Configure local xdotool in monaco (the text-editor on the right) using this config: +2. Enter settings port `-1` tells nodecg-io to use a locally installed xdotool: ```json { @@ -30,6 +30,7 @@ The Xdotool sample bundle in `samples/xdotool-windowminimize` shows how to use t After entering it, click save. -6. Set the created xdotool service instance to the service dependency of the xdotool bundle. +3. Set the sample's (`xdotool-windowminimize`) dependency to be the newly + created service instance (of type `xdotool`). -7. Your browser window should get minimized. +4. Your browser window should get minimized. diff --git a/docs/samples/youtube.md b/docs/samples/youtube.md index b88c6745..4af41a98 100644 --- a/docs/samples/youtube.md +++ b/docs/samples/youtube.md @@ -1,29 +1,32 @@ ## Using the YouTube sample bundle -The YouTube bundle in `samples/youtube-playlist` demonstrates the ability of getting information of a playlist. Here is a guide to how to get it working. +The YouTube bundle in `samples/youtube-playlist` demonstrates the ability of +getting information of a playlist. Here is a guide to how to get it working. ### Prerequisites -- Working NodeCG & nodecg-io installation +You will need a working `nodecg-io` installation. If you have non yet take a +look at [installation guide](../getting_started/install.md). You may need to +install this bundle, so take a look at the +[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide. It +will also tell you how to log in and how to use the GUI. + +**You also need:** + - Google cloud API OAuth access (client ID, client Secret) - Grant `YouTube Data API v3` access at the project's dashboard. - - Shortcut URL: > + - Shortcut URL: + > -_Note:_ If you don't have such a key yet, you can generate them like [this](https://developers.google.com/identity/protocols/oauth2/web-server#creatingcred). As redirect URI add . +_Note:_ If you don't have such a key yet, you can generate them like +[this](https://developers.google.com/identity/protocols/oauth2/web-server#creatingcred). +As redirect URI add . ### Configure the YouTube sample bundle -1. Start nodecg with nodecg-io installed. The YouTube 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. +1. In NodeCG, create a new googleapis service instance. -4. Create a new googleapis service instance using the left upper menu. - -5. Enter credentials for googleapis. - - The created instance should be automatically selected, if not select it in the upper left menu. Enter your YouTube OAuth credentials in monaco (the text-editor on the right) in this format: +2. Enter your YouTube OAuth credentials: ```json { @@ -35,13 +38,13 @@ _Note:_ If you don't have such a key yet, you can generate them like [this](http After entering it, click save. - _Note:_ If you don't see monaco on the right, try reloading the page. - _Note:_ You can add multiple scopes if the googleapis instance is used for multiple bundles. - -6. Set the created googleapis service instance to the service dependency of the YouTube bundle. + _Note:_ You can add multiple scopes if the googleapis instance is used for + multiple bundles. - Select the YouTube bundle and the googleapis service in the left bottom menu and then select the service instance that should be used by the YouTube bundle (in this case the name of the previously created googleapis instance). +3. Set the sample's (`youtube-playlist`) dependency to be the newly created + service instance (of type `googleapis`). -7. Check the nodecg logs +4. Check the NodeCG logs: - You should see an error or a success message that is hardcoded in `samples/youtube-playlist/extension/index.ts`. + You should see an error or a success message that is hardcoded in + `samples/youtube-playlist/extension/index.ts`. diff --git a/mkdocs.yml b/mkdocs.yml index 165b8902..4c30b4d0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -38,6 +38,7 @@ nav: - Home: index.md - Getting Started: - Installation: getting_started/install.md + - Using a sample bundle: getting_started/try_example_bundle.md - Your first bundle: getting_started/create_new_bundle.md - Migrating an existing bundle: getting_started/existing_bundle.md - Configuration: getting_started/configuration.md