Developer Note: Engage Interop with 3rd-party Systems

Using MELPe

MELPe is a coding standard used for highly compressed voice operating over severly bandwidth constrained networks. While it's been around for a long time (and is rather outdated in many respects), MELPe is still in widespread use in the military community worldwide. So, obviously, we support it in Engage.

However ... unlike other CODECs that Engage supports, MELPe is subject to intellectual property protections and is only availabe from a limited number of commercial vendors. The result is that we cannot simply include MELPe as a standard option in Engage without putting some protections around it for purposes of license tracking for those commercial entities.

So, what we do in Engage is to enable the use of its MELPe support through inclusion of a featureset JSON object in the Engine policy configuration.

What's super-important here is that the JSON object is tied to the license for the Engage Engine. This means that you can't just use a featureset from any other licensed Engage Engine and expect it to work with the license for your Engine. (Yeah, this is a pain but we have little choice in ensuring that MELPe is not used outside of the licensing agreements we have with the MELPe vendors.)

Here's an example of a featureset:

"featureset": {                  
    "signature": "1DB23AFD62AC49B8ABFB8C01241793621CACC3CC831D4898B0BD868AF6928E31",
    "features": [
      {
        "id": "{2BE94F5E-5630-4487-AAB6-77D820BB505A}",
        "count": -1,
        "comments": "MELPe CODEC"
      }
    ]
}

In this example, our featureset contains just a single element - that being for MELPe as identified by its ID of {2BE94F5E-5630-4487-AAB6-77D820BB505A}. Also, you'll notice the count having a value of -1 - this means that the Engine is allowed to create an unlimited number of instances of the CODEC. (If count had a positive number - say 6 - then only 6 instances would be allowed to be created at any one time.)

Now, what ties this featureset to the license is the signature field. This field is a SHA256 hash of the ordered contents of the featureset (including their counts) combined with the license (and some other internal values). So ... if you use a featureset with a particular signature along with the license associated with that signature; you'd be good. But, if you take that featureset (with the same signature) and try to use with with a different license, Engage is going to bark at you and reject the configuration. Basically, your API call to engageInitialize() will fail!

Hooking Up With Trellisware

TODO: Elaborate

While Engage can communicate with MANET radios from Trellisware; there's a few items to be aware of:

1. The ingress and egress multicast addresses on the Trellisware MNG need to be the same.

2. The ingress and egress IP ports on the Trellisware MNG need to be the same (they're not by default).

3. Trellisware does NOT support RTP traffic encryption on the enterprise network so, therefore, your group cannot have encryption. In other words, the cryptoPassword field must be empty or simply not provided.

4. Trellisware does not support all the CODECs that Engage supports so we need to be sure that the CODEC selected on Engage matches the CODEC selected on the MNG.

Group Configuration

{
    "id": "{E63EAFBB-FE39-46C4-B23C-88E52308AB79}",
    "type": 1,
    "name": "Trellisware MELPe Group",

    "timeline": {
        "enabled": true,
        "maxAudioTimeMs": 60000
    },

    "rx": {
        "address": "239.1.2.1",
        "port": 20002
    },

    "tx": {
        "address": "239.1.2.1",
        "port": 20002
    },


    "txAudio": {
        "encoder": 52,
        "customRtpPayloadType": 117
    },

    "inboundRtpPayloadTypeTranslations":[
        { 
            "external": 117, 
            "engage" : 77 
        }
    ]
}

• id The Engage ID of the group.

• type This is an audio group so the value is 1.

• name The group's name.

• timeline In this object we've enabled timeline recording for the group and specified a maximum number of 60 seconds (60000 milliseconds) for the recording time window.

• rx and tx These two specify the multicast address and port to be used to ship audio traffic back and forth with the Trellisware system. In 99% of cases, rx and tx would be the same and would need to match the ingress and egress settings for the channel configured on the Trellisware Multinet Gateway.

• txAudio There's a bunch of options for the txAudio object but we can let Engage use its defaults for the most part. However, we do need to tell Engage what CODEC to use for transmission. In this case, we're going to use MELPe at 2,400 bps which, in Engage-world, is defined as a value of 52. (By the way, a value of 51 represents MELP at 1,200 bps. A value of 50 represents MELPe at 600 bps.) Also, we need to make sure that Trellisware will pay attention to the RTP packets we send to it - and that's done with a field in the RTP packet known as the payload type. Now, by default, Engage will use 77 as a payload type for MELP at 2,400 bps. But Trellisware uses a payload type of 117 - and that's not easily changed on the Trellisware side. So, we need to tell Engage to transmit its RTP packets using the custom payload type of 117. That's the setting you want to make for customRtpPayloadType.

• inboundRtpPayloadTypeTranslations Going on the above and understanding therefore that Trellisware is going to transmit a payload type of 117, we need to tell Engage what that means - i.e. "Hey, Engage, when you see a RTP payload type of 117, you need to treat that as MELPe at 2,400." We do this by including the inboundRtpPayloadTypeTranslations object that tells Engage how to perform these translations. This object is an array of translation objects so you could technically have a whole bunch of translations. For our purposes though, we're just going to define a single element wherein we define the external value (that coming from Trellisware) to be 117 and the corresponding Engage value to be 77.

MELPe @ 0.6 kbps

Item	Value	Comments
cryptoPassword	(null)
txAudio / encoder	50
txAudio / customRtpPayloadType	117	NOT VERIFIED !!!
inboundRtpPayloadTypeTranslations / external	117	NOT VERIFIED !!!
inboundRtpPayloadTypeTranslations / engage	79

MELPe @ 1.2 kbps

Item	Value	Comments
cryptoPassword	(null)
txAudio / encoder	51
txAudio / customRtpPayloadType	117	NOT VERIFIED !!!
inboundRtpPayloadTypeTranslations / external	117	NOT VERIFIED !!!
inboundRtpPayloadTypeTranslations / engage	78

MELPe @ 2.4 kbps

Item	Value	Comments
cryptoPassword	(null)
txAudio / encoder	52
txAudio / customRtpPayloadType	117
inboundRtpPayloadTypeTranslations / external	117
inboundRtpPayloadTypeTranslations / engage	77