Open API documentation for the AMX CE control boxes

richardherman

Is there any place I can download the 'Open-API' documentation for the AMX CE control boxes? It's not in the download section or the manual as far as I can tell. There is a Duet module made for it, so the API must be stable enough for that, so it probably exists somewhere.
Am I just missing something?

[Deleted User]

Richard, I have attached a draft document that should get you going. The original plan was for the open API to be HControl, and that is what it currently offers. However, for serial, you need to encode strings in base64 and we felt that would not be quite as programmer friendly as we would like. So, a secondary/simplified open api has just made it out of test and validation and documentation for that is in the works. This PDF should be posted to the web shortly.

The duet module was intended to simplify adoption in a NX environment, but the API is important in all other environments.

dansblee

Hi,

I was just handed a pile of the new CE control boxes (specifically CE-COM2 and CE-IRS4) to integrate into a traditional NetLinx system. I found the above document already published on the AMX product page and have been trying for several days to find a way to actually send the API Commands listed to the boxes but without any success.

Opening standard Telnet to port 4197 can’t seem to accept any string input and returns unknown command after each Character!

Can you elaborate a little about how actually we can use the Open-API above in a traditional NetLinx environment with the new CE-control boxes? Especially if moving forward HControl will become the defecto control protocol for Harman products, I think more information needs to be a made available.

Thank you!

[Deleted User]

In a traditional Netlinx world, I would suggest trying the Duet Module made for these. The intent as to make them perform more like an EXB box in a semi-native manner.

https://developer.amx.com/#!/searchresult?Manufacturer=AMX&Model=CE

richardherman

@dansblee said:

Opening standard Telnet to port 4197 can’t seem to accept any string input and returns unknown command after each Character!

Can you even use telnet? can't see any mention of that in the manual. Open a TCP connection (IP_CLIENT_OPEN) to port 4197 and send the JSON formatted commands. There is no native Netlinx JSON parser, but if you need it there are a few around, written in Netlinx.

Probably worth it to avoid the module, especially is what you need to do is relatively simple.

Mind you, I haven't use these CE boxes before, just going by what I read in the manual. So take this as friendly but not very informed advice...

John Nagy

Progress once again makes life harder.

dansblee

Richard : Unfortunately telnet to 4197 doesn’t work properly. It can open the connection but I can’t type in the exec strings from the API list. It seems to parse each character individually rather then wait for a CR or EOL and error out that @e is not a known command immediately!

Chris : I’ll take a gander at the Duet Module but to be honest I come come the traditional NetLinx environment and have never used Duet in any form. So yes, progress is 2 steps back to get one step forward… The should (or must) be an easier way given the simplicity of the CE boxes…

richardherman

@dansblee said:
Richard : Unfortunately telnet to 4197 doesn’t work properly. It can open the connection but I can’t type in the exec strings from the API list. It seems to parse each character individually rather then wait for a CR or EOL and error out that @e is not a known command immediately!

That's what I said: you probably can't use telnet. If you want to test without writing a Netlinx test program, use a utility like :

https://hw-group.com/software/hercules-setup-utility

[Deleted User]

A choice was made to make this unit HControl and not native Netlinx. In terms of the calendar, this product made it out before Muse and thus the odd conundrum of native protocols. The module let's you use it like a regular native port and you can even route a different duet module through this to reach the end device.

I was not all that familiar with Duet modules when I started in the professional services team at AMX almost 15 years ago. I quickly learned the power of this driver type in larger deployed template systems where the programmer coded to SNAPI and you could plug-and-play drivers from a web page when the system design called for a different model. Not having access to source is a common complaint, and I have been at the rack at 2am enough times to understand the root of the issue being that one cannot self serve to get out of a jam. However, now being on the other side of the equation, I can tell you that we are quite responsive in live support situations to "quickly" get a revision to a systems integrator in need at a jobsite. The reality is that we can do far more in Java than we can in traditional Netlinx programming. In this case, it serves as a bridge between the Netlinx and Muse worlds. Making embedded devices communicate with different protocols is no easy task and there is both a time and financial impact to making these choices. From what we have seen, the only tricky part of working with the CE boxes is with the COM2 unit because of the need for escape characters. By default, the unit is wanting base64, but alternatives were put in place to allow your code to be human readable. There is nuance, but my team has found success through tinkering and so will you. The module removes the implementation complexity in Netlinx deployments. We have updated the ZoomRoom controls JSON builder for these products as well for use cases without an AMX controller. That too is another reference guide to understand the syntax structure.

HARMAN_Nick

I have some NetLinx code for three of the four CE boxes that make them work like the EXB. (The fourth, CE-IO4, does not map at all to the EXB-IO8. It has distinct input modes as well as analog in.)

The code is ugly only because of the 'pretending to be an EXB' part. I used some shenanigans from 20 years ago to make it be able to send and receive distinct strings on a virtual device, which gets super ugly on multiple ports.

The remaining code is relatively clean. I used the BASE64 routine from i!-EquipmentMonitor (MIME attachment support). I extended that to allow for decode as well. You can certainly lift the strings from the code and ignore the EXB emulation.

I'll work with Chris to get it posted.

HARMAN_Nick

Here's the code.

dansblee

@HARMAN_Nick said:
Here's the code.

Thank you! I’ll take a gander at the code shortly. Much appreciated!

DanielLee

@HARMAN_Nick said:
Here's the code.

Hi Nick,

I just finally got the chance to down and look at the code. Do you happen to have the CE-IRS8 module code also? The file you uploaded only has the COM2 and REL8 module code.

Thank you in advance for the help. This is significantly helpful at this point as I'm at the stage of pulling my hair out.

DanielLee

@HARMAN_Chris said:
In a traditional Netlinx world, I would suggest trying the Duet Module made for these. The intent as to make them perform more like an EXB box in a semi-native manner.

https://developer.amx.com/#!/searchresult?Manufacturer=AMX&Model=CE

Hi Chris,

I downloaded and looked the the CE-IRS4 example code. One quick question, where or how do I define the correct .irl file to be used? In the example code this is defined for the Appleoo4.irl but I don't see anywhere that this is defined. I'm a little confused by this as there is a field in the device webpage to actually upload the .irl file and then another to actually select the correct one to use from the list of .irl files uploaded.

Thanks!

[Deleted User]

Question 1: how do I define the correct .irl file to be used?
-for the CE box, the web interface of the CE box is where you will upload the .irl - the module is essentially only instructing the CE box to fire the command found in slot X of the CE box.

Question 2: In the example code this is defined for the Appleoo4.irl but I don't see anywhere that this is defined.
-The example provided is AppleTV, but in the case of this device, you are not mapping it to a physical port in the workspace as you would in a traditional native netlinx DPS environment. Netlinx Studio is not handling the file transfer to this appliance. You will manually send it through the device webpage or through the Manager application.

Question 3: confused by this as there is a field in the device webpage to actually upload the .irl file and then another to actually select the correct one to use from the list of .irl files uploaded.
-This functionality is similar in Muse. The upload is effectively a file folder repository. The second field is a drop down list that contains the file names from the folder. One is a pool of possible IR files that could be used, and the second is mapping this to the specific port that uses the file. You may have 4 different appleTV appliances that all use the 1 uploaded IR file. If so, the IR file is a shared resource and there is no need to upload the same file 4 times.

DanielLee

This has been most helpful. However, I think the documentation is slightly lacking. Thank you in advance for the assistance and information! I'm still a little confused though.

What is the correct approach when we have multiple devices with different IR profiles since the IRS4 has 4 ports?

Does this imply that I have to manually upload the different .irl file(s) to each device then go into the webpage and assign the correct profile to the individual ports, ie. if I have 4 devices being controlled by IR, I have to load all 4 .irl files then assign them from the device webpage to the correct port?

Is there a function within the Duet modules to do this assignment which we can call when the the devices come online?

[Deleted User]

"Does this imply that I have to manually upload the different .irl file(s) to each device then go into the webpage and assign the correct profile to the individual ports" - YES

The virtual devices in the example code represent the 4 output ports of the IRS4. I spoke to the developer who authored the demo code and can elaborate on some of the bits that do not jump out at you on the screen.

vdvCE_IRS4      =    41001:1:0  // CE-IRS4 BOX BRIDGE MODULE
vdvCE_IRS4_P1       =    33001:1:0  // CE-IRS4 PORT 1 (MUST BE PORT 1, REF FOR MODULE)
vdvCE_IRS4_P2       =    33001:2:0  // CE-IRS4 PORT 2
vdvCE_IRS4_P3       =    33001:3:0  // CE-IRS4 PORT 3
vdvCE_IRS4_P4       =    33001:4:0  // CE-IRS4 PORT 4

In the device definition, we need a duet virtual device as the parent, and then we need however many non-duet virtual devices that your CE box supports.

dvAppleTV           =    33001:1:0  //NOTE this is the same device as vdvCE_IRS4_P1.  This is simply showing a friendly name here

Here, the developer wants to refer to his device with a more meaningful friendly name. As you can see - he used the same device number as port 1 and it basically creates a second reference name for the same virtual device.
You could simply use your preferred name in the first declaration.

vdvCE_IRS4      =    41001:1:0  // CE-IRS4 BOX BRIDGE MODULE
dvAppleTV           =    33001:1:0  // CE-IRS4 PORT 1 (MUST BE PORT 1, REF FOR MODULE)
dvDirecTV           =    33001:2:0  // CE-IRS4 PORT 2
dvBluray            =    33001:3:0  // CE-IRS4 PORT 3
dvSamsungWall       =    33001:4:0  // CE-IRS4 PORT 4

Whichever approach you use, include the PORT1 definition as the second part of the DEFINE_MODULE statement

DEFINE_MODULE 'AMX_CE_Control_Comm_dr1_0_0'     mdlCEDEVICE001(vdvCE_IRS4, vdvCE_IRS4_P1);  // ALWAYS PORT PASS IN PORT 1

The developer made a choice here that is not totally obvious. In defining the duet module, he wants to include the virtual device for the module - vdvCE_IRS4 - and then associate it with the virtual device of the FIRST port. His assumption is that you are going to number these sequentially. The module knows that an IRS4 contains 4 ports, so once it has the address of the first virtual device, it auto- assigns the remaining ports in code

vdvCE_IRS4_P1       =    33001:1:0  // CE-IRS4 PORT 1 (MUST BE PORT 1, REF FOR MODULE)
vdvCE_IRS4_P2       =    33001:2:0  // CE-IRS4 PORT 2
vdvCE_IRS4_P3       =    33001:3:0  // CE-IRS4 PORT 3
vdvCE_IRS4_P4       =    33001:4:0  // CE-IRS4 PORT 4

You can see that these declarations have the same DEVICE number (33001), but different PORT numbers and that the port numbers are in numerical order 1-4.

The example code then shows how they handle various events - and they look like normal IR events in netlinx programming.

Rustamakhan

It seems like you've thoroughly checked the download section and manual for the AMX CE control boxes without finding the Open-API documentation. It's possible that the documentation might be available through a separate channel or resource. Have you tried reaching out directly to AMX support or searching their online forums or community for more information? They might be able to point you in the right direction or provide access to the documentation you're looking for.

richardherman

AI entering the forum?