Tag Archive: macros

Some devices in a cinema’s ecosystem use HTTP Requests for communication. The JNIOR’s Cinema application can send GET and POST Requests to these devices by defining them in the Macro and Device files. This post will go over how to declare a HTTP Device in Cinema and send commands to it. If this is your first time creating Macro and Device files for the Cinema application, please check out this post first that goes over creating Macro and Device files in general. 

To start, you’ll want to open the JNIOR Support Tool and navigate to the Device Tab. You’ll start by going to the bottom left of the Support Tool and select ‘Add’. This will add a new device configuration to the Device Tab. Here you are then going to declare an HTTP Request device that will represent the device you are going to send HTTP Requests to. For this example I’m going to name it HTTP_Example (The name can’t have any spaces). The device type should be HTTP Request, the IP should be the whatever your device’s IP is set to (I used IP 10.0.0.201 for this example), and the port number should be 80. Once all this is set you should have the following device configuration:

Once you have this, you’ll save this device configuration on your computer (it should automatically open to a directory for you to save it in, but if you change the location make sure you remember where you save it), and then you’ll publish it to the JNIOR you want your HTTP device to receive commands from. Once you do that, you’ll then navigate to the Macro Tab.

On the Macro Tab, the first thing you must do is link your Device file with the Macro file you are going to create, so you can reference the Device you just declared in your Macros. This can be done by selecting the ‘Link Devices’ button at the top of the Macro Tab, and then selecting the Device file wherever you saved it on your computer. You’ll then need to create macros that will execute our actions. Macros can be added to the Macro View by clicking the ‘Add’ button at the bottom left of the Macro Tab. In this example I create two, one for doing a GET called HTTP Get, and one for doing a POST called HTTP Post. Once you have your macros, you’ll then need to create the actions the macros will execute to send to your HTTP device. You’ll add actions using the ‘Add’ button at the bottom of the Macro Tab under the Action View. In this example I name them after the HTTP Requests they are going to perform, one being GET, and one being POST. For these actions, you then set the Device for the actions to the HTTP_Example device you created from your Device file. For the GET action, it should be GET, and for the POST action it should be POST. Lastly for the actions, you enter the commands you need to send to your HTTP device in the Data field. Now that you have your macros and the actions you need them to perform, you just need to add the actions to your macros. To do this, select one of your macros so that it is highlighted, then do the same for the action you want to add to it. Once they both are highlighted, hit the arrow in-between the Macro View and Action View, and it should add the action to the macro. Do this for the other macro and your configuration should look like this:

Now save and publish this Macro file to the JNIOR that should be sending to your HTTP Device. Now when these macros are executed on your JNIOR, they should send the commands you defined to your HTTP device!

What is an escape sequence?

From Wikipedia, an escape sequence is a combination of characters that has a meaning other than the literal characters contained therein.  Ab Escape Sequence starts with a backslash (\) and is followed by a character.  The most common Escape Sequences would be \r for carriage return and \n for linefeed.  These are usually used to denote a break between commands.  Some Escape Sequences can require additional information to be included in the sequence.

It is important to understand that these escape sequences get converted before sending the bytes.  The escape sequences differ from device to device and the correct sequence is defined by the device you are sending from.  One device might want a carriage return entered as \r, like the JNIOR, and another might want it entered as \0d

What Escape Sequences are available?

\0: NULL
\r: Carriage Return
\n: Linefeed
\b: Backspace
\t: Tab
\\: Backslash
\”: Double Quote
\x##: HEX value

Here we see the example where the \x requires two more digits to be entered following the \x.  These digits are hexadecimal digits (0-9, a-f, A-F).  Capitalization does not matter.  Any value can be entered as a HEX value.  For instance, \r has a decimal value of 13 or a hexadecimal value of 0d and can be entered as \x0d.  The lowercase letter k has a hexadecimal value of 6b and can be entered as \x6b.  It is much easier to use printable characters where you can.  Printable characters and escape sequences can be intermixed.

Sometimes a double quote (“) cannot be entered because it has another meaning.  For example, when declaring a string we start and end that string with a double quote.  Entering a double quote in the middle of that string would confuse the code about where the string should actually end.  In this case, we can escape that interior double quote.

Special Note about Commas

Commas in Cinema Actions are special.  Unfortunately, the macro file is stored in CSV format.  That means all fields are separated by commas.  Entering a comma in the data field for an action will confuse the whole macro file.  The prevent confusion you should escape the comma and use the hexadecimal value \x2c.

Special Note about Double Quotes

Double quotes are also special in Cinema Actions.  At one time they were used as in the above example to define strings.  Double quotes should always be escaped.  There is a special escape sequence for double quotes, \",  where there are not for commas.

While the Cinema application has the functionality to send a UDP command to another JNIOR, did you know that it can do a UDP broadcast command also? This allows the JNIOR to send a UDP command to any JNIORs listening on that UDP port at the same time. This post will explain how to set this up. This post assumes you’ve already installed the Cinema application on your JNIOR. If you haven’t, here is a post that shows you how to install Cinema on your JNIOR.

Device File

First, to setup the broadcast you need to create a RAW UDP device in the support tool under the device tab. Here you can add a device from the ‘Add’ button at the bottom of the Device tab, and after naming it (I’ve named it ‘UDP_Broadcast’ for this example) you assign it as a RAW UDP device type. For the IP Address, it needs to be set to 255.255.255.255 so when this device is sent to from a macro command, it will send to any device listening on the same UDP port. The UDP port will be whatever UDP port you want to broadcast on. Just make sure the devices you are broadcasting to are also listening on that same UDP port (This example uses port 5554).

Macro File

Once this device is setup, you’ll save the device file locally and publish it to the JNIOR that will be broadcasting the command. You’ll then move onto the Macro tab in the JNIOR support tool. The first thing to do here is to select the ‘Link Devices’ option and select the device file you just created. This allows you to reference the ‘UDP_Broadcast’ device you created in your macros. Here in the Macro tab, a macro can be made that sends a command out to JNIORs via the UDP_Broadcast device. You’ll select the ‘Add’ button at the bottom left of the Macro tab, and this will add a macro in the macro view. You’ll name the macro (I’ve named it ‘Hello’ for this example) and then you’ll add an action to this macro. You’ll select the ‘Add’ button at the bottom right of the Macro tab this time, and add an action to the action view. Here you’ll name the action (I’ve named it ‘Broadcast Hello’ for this example) and then you’ll set the action’s device to the ‘UDP_Broadcast’ device from the device file we created. After this you’ll select the ‘send’ action for the macro, and for the data you can enter the whatever data you want to broadcast to other devices (I’ve made the data ‘Hello’ for this example). Lastly, you’ll select the macro ‘Hello’ and the action ‘Broadcast Hello’ at the same time, and then select the ‘<-‘ button between the Macro and Action views. This will add the ‘Broadcast Hello’ action to the ‘Hello’ Macro. After this you’ll save the macro file locally and publish it to the JNIOR that will be broadcasting the command.

Setting Cinema UDP Port

Your JNIOR should now be setup so when the ‘Hello’ macro is activated, it will broadcast to any JNIOR listening on port 5554 the command ‘Hello’. If you are trying to broadcast to other JNIOR’s running Cinema, you can send UDP commands to their Cinema application directly. Just make sure you have Cinema’s UDP port setup for each JNIOR that should be listening for those UDP commands. You can do this by going to the registry of a JNIOR, and under AppData/Cinema/ you set the registry key UdpServerPortNumber to the UDP port Cinema should be listening on. After setting this registry key, make sure to reboot that JNIOR so the change takes effect.

When using the Cinema application to send/receive commands to JNIOR, you may want to better customize the actions your JNIOR can perform past just controlling the JNIOR’s I/O. Creating macros is a great way to get more functionality from sending/receiving commands to the JNIOR. This post will explain how to create and upload macros to your JNIOR.

To create macros you need to have the support tool downloaded, which you can get here.

Name Version Release Date Size MD5
JNIOR Support Tool v7.15 Nov 20 2023 10.5 MB 688524ba37066aab6e327a79f0cfb0b5

Creating Macros

Once the support tool is downloaded, you’ll open it and go to the macro tab. In the macro tab, you can create and upload macros to your JNIOR. To add a new macro, you’ll select the ‘add’ button at the bottom left of the update tab and select ‘macro’. With the new macro added, you can click on the new macro to edit its name.

Adding Actions to Macros

After adding and naming the macro, you can then add actions to the macro. The actions are on the right side of the update tab and you can add new actions at the bottom of the action view, or edit existing ones by selecting them and editing the values in their columns. By selecting the macro and then the action you can select the arrow button between them to add the action to the macro.

Editing the Macro Cue

Macros can be set to trigger at different times by editing their timing. While an action is selected in a macro, you can press the various timing buttons on the right to add or reduce the time it takes to trigger that action in the macro.

You can also move your macros by shifting them up and down with the Up/Dn buttons. This doesn’t change how the macros execute, but can help you keep your macros in organized.

Once you finish adding your macros and actions, you’ll then need to save and publish your macro file to your JNIOR by selecting the ‘publish to JNIOR’ button. This will prompt you to save your macro file. After you save, you can then select your JNIOR to publish to. With that, you’ll have created and published your macro file to a JNIOR. Now when the JNIOR receives a command to execute a macro you created, it will go through and execute each action inside the macro in order.

Opening an Existing Macro File

Instead of creating a Macro file, you can open one that has already been created and saved. Selecting the Open Local File button will open your file explorer to where Macro files are saved on your PC. Here you can select one you wish to open, and it will populate into the Support Tool Macro tab. You can also select the Open Remote File button, which will open a JNIOR selection screen and allow you to open a Macro file that is loaded on a JNIOR.

Referencing Devices from your Device file in Macros

You may have external devices that you want to control from a JNIOR macro. To do this you first need to create and publish a Device file to the JNIOR. Once that is done, at the top of the Macro tab you’ll want to select the Link Devices button. Your file explorer will open to where your Device files are saved, and you’ll select the one you want to use. With this, you’ll now be able to reference any Device you created in the Device file as a device you can use in the Device column of your actions! If this didn’t work, here is a more detailed walkthrough of this.

You can use the scheduling in Cinema.jar to schedule macros daily, weekly or monthly. When Cinema.jar is installed and executed for the first time it will create 3 default keys. They will look like this in the registry. 

Below are examples for the logic you can implement in Cinema using these registries.

OnIOChange

This logic expression will be checked whenever the JNIOR I/O changes. The I/O that can be monitored are the internal inputs and outputs on the JNIOR as well as any outputs on a 4 relay output expansion module.

OnIOChange, din1 and din2, run test

For the above example, each time either input 1 or 2 changes, the logic rule (din1 AND din2) will be evaluated and the macro (test) will execute if both inputs are ON.

OnPreshowClient()

This logic expression will be checked whenever the Preshow Client in Cinema.JAR receives a message. To specify the string/message that will cause the logic to be evaluated put it inside the parenthesis.

OnPreshowClient(start), din3 and din4, run preshow start

For the above example, each time the device connected to the JNIOR as the Preshow Client sends the string “start” to Cinema.JAR, the logic rule (din3 AND din4) will be evaluated and the macro (preshow start) will execute if both inputs are ON.

OnCinemaServer()

This logic expression will be checked whenever the Cinema Server Client in Cinema.JAR receives a message. To specify the string/message that will cause the logic to be evaluated put it inside the parenthesis.

OnCinemaServer(movie), din5 or din6, run movie start

For the above example, each time the device connected to the JNIOR as the Cinema Server Client sends the string “movie”, the logic (din5 OR din6) will be evaluated and the macro (movie start) will be run if either digital input is ON.

OnMacro()

This logic expression will be evaluated whenever the named macro has been requested to run. This logic expression can be used as a ‘lock’ to make sure certain macros can only execute when a certain I/O state exists or cannot be executed when a certain I/O state exists. To specify the macro that is bound by this logic place its name inside the parenthesis.

OnMacro(flat start), din7

For the above example, if the macro “flat start” is triggered to run via any method, the logic (din7) will be checked. If (din7) is ON, the macro will be allowed to run. If (din7) is OFF, the macro will not be allowed to run. 

Below is an example registry using some of the examples above.

This post assumes you have the Cinema application installed on your JNIOR, and a macro created and published to your JNIOR. If you don’t know how to create a macro command for a JNIOR to send to external devices, here is a post on Sending Commands from a JNIOR to a Device with Cinema.

When you create macros for Cinema, there are many ways they can be triggered. One of these ways is by setting the macro names in the trigger registry for Cinema. To do this, the first thing we’ll want to do is go to the JNIOR Web UI by selecting the JNIOR in the beacon tab of the support tool. There you’ll right click it, and go to tools/open web page. Once on the JNIOR web page, you’ll go to the registry tab. On the registry tab, you’ll select AppData/Cinema/Triggers. Once there, you’ll go to any of the registry keys named either ‘Input#Macro’ or ‘Output#Macro’ and enter the name of the macro we created in the support tool. We named it ExampleMacro, but if you named it something different you’ll enter that name here. This should set the JNIOR so that when that I/O value on the JNIOR you picked goes ON, the macro will activate. 

 

When creating a macro using the JNIOR Support Tool, you may want data being sent in a command to contain quotes. This can be done, but its important to know how. When adding quotes, you can’t type them directly in because it will disrupt the csv format that macro files are saved as. To get around this, you type the hex value for quotes in the data field to implement them, which is \x22. So as an example if you had a macro named Play and you wanted to surround in quotes when adding it in the data field of a macro action, you would type \x22Play\x22 instead of “Play” in the data field of a macro action.

Macro tab of the JNIOR Support Tool

The Tasker application has been made to handle lots of different types of functionality. This post will go over an example that looks into different actions in Tasker such as a While Loop, If Statement, TCP Send and Set Variable action. It will also create devices in Tasker that would be sent to. The example should monitor output 1’s state, and when it turns on it will send string commands out to devices we declared. 

Actions In Example

The Set Variable Action

Tasker Set Variable Action

The Set Variable Action allows you to create a variable in the first value field of the action, and then assign it a value in the second value field.

The If Statement Action

An If Block Action creates a condition using a variable, that activates other actions when the condition is meet.

The While Loop Action

The While Loop Action makes actions within it reiterate until the conditional in the value field is met. 

The TCP Send Action

The TCP Send Action allows you to select a device created in the device tab, and send it the info you define. The device value created in the device tab uses an IP address and port number of the device. This is used to create the TCP connection you send on.

Device Example

Note: Values in this example will most likely differ from your. Information you enter here depends on what settings your Ethernet device listens on.

In this Example, before we create the Tasks, we need to create the devices that will receive commands we send, like shown above. To start, go to the device tab and click the “Add Device” button. Add as many devices you plan to send to. Each device you’ll enter its IP address, and TCP Port number.

After creating the devices to send macros to, you’ll start creating the task. It starts with the Set Variable action. This action is used to define the variable of the while loop to know when to end the Task. We set this variable to true so the while loop never stops until we set the variable to false. Once this value is defined, a while loop is added to the task. We’ll set this loop to check the conditional of the variable we created. After that, we add an if block and set the conditional of it.  This evaluates output 1 on the JNIOR, and if the output’s state is on, then if begins doing the actions inside the if block. When output 1 does go high, it sends the devices we created the string ‘test’ using TCP Send actions. It also sets the conditional for the while loop to false, so the task no longer loops, and ends.

With this, you should have a task that constantly monitors output 1 on the JNIOR. If output 1 goes high, it sends the string ‘test’ to all the defined devices.

You can use the Cinema application to execute DMX scripts. Those scripts can be on the same JNIOR or on another JNIOR. Both situations require making a TCP or Raw Ethernet connection to port 10000.

To execute a script once you will send go SCRIPTNAME\r\n

To execute a script a certain number of times you will send the same command but with a repeat parameter. For example, to execute 3 times we would send go SCRIPTNAME -r 3\r\n

To execute a script and have it repeat forever, until you abort it or reboot the JNIOR, you will send the -f parameter. For example, go SCRIPTNAME -f\r\n

Create a DMX device to use in the Macro

Create a Macro to call a DMX script with the Device we just created

Macro tab of the JNIOR Support Tool