Connectors


Name: Can be whatever the vendor wants. Generally good practice to put type of connector and the Vendor name in the Name. e.g. HTTP_Name_Number01


Description: again, can be anything to differentiate between other connectors. 


Assembly: Same for all connectors of same type (Main connectors below):

  • HTTP:  Http\DME.DeviceServer.Connector.Http.dll
  • TCP:    FlexiTcp\DME.DeviceServer.Connector.FlexiTcp.dll
  • Multi:  Multi\DME.DeviceServer.Connector.MultiConnector.dll


Configuration: This is basically the same format with different values and a few different fields for each connector. Each TCP address needs to have a port declared.


The connector setup uses XML. There are requirements to this so the connector can be saved.

A common error that causes connectors to fail XML validation is ampersands & - they need to be escaped - to do this replace with &


If you are getting errors you can use something like this to check

https://www.xmlvalidation.com/ 




HTTP Fields:

<add key="url" value="http://Addressgoeshere"/

Where to put the URL, this is always needed


<add key="format" value="JSON"/>

JSON format, needed in all cases


 <add key="header1" value="header text"/>

A number of headers can be added to the HTTP POST depending on what is needed. Often Basic Authentication is needed. 


<add key="showPostElpasedTime" value="false"/>

When true, this actually times the post to the 3rd party and puts the result into the log (occasionally useful). Defaults to false. Safe to leave out, unless you need it.


Dynamic Fields:

Various dynamic fields can be entered into connectors, which changed based upon the device sending the data.


[SERIAL]

Inputs the serial of the device wherever you add it. 

E.g. you might add it in the URL


<add key="url" value="http://Addressgoeshere/devices/[SERIAL]"/>


    [CUSTOM1], [CUSTOM2], [CUSTOM3]


The OEM API can be used to load these values into a table against device serials. Developed initially to fit requirements of the Azure IoT Hub. 

Handy if you need an authentication token per device.


Authentication examples


<add key="url" value="http://dm.agritrackapi.com/v1/dm/serial/[SERIAL]/"/>

<add key="format" value="JSON"/>
<add key="username" value="dm_connect"/>
<add key="password" value="2hHGZ3ne39NJRWDNwZ"/>
<add key="forceBasicAuthentication" value="true"/>


Header examples:

<add key="header1" value="SomeHeader:Value"/> -- you can include some random readers with this.

<add key="header2" value="Authorization:Basic KHJSGKJHG"/> -- this could be used instead of the username/password tags above – base64 encode the username:password

<add key="headerX" value="Authorization:Bearer KHJSGKJHG"/> -- this could be used if they give me a token.


<add key="header#" value="HeaderName: valueHereInBase64"/>



HTTP examples:


"Basic/Standard" Connector

<configuration>

<appSettings>

<add key="url" value="http://Addressgoeshere"/>

<add key="format" value="JSON"/>

</appSettings>

</configuration>


Connector with Basic Authentication

<configuration><appSettings>

<add key="url" value="URL goes here"/>

<add key="format" value="JSON"/>

<add key="header1" value="Authorization:basic ZGlnaXRhbG1hdHRlcjpkbTEyMzQ="/>

</appSettings></configuration>


The highlighted section is the base64 encoded user:password


i.e. 

Username - digitalmatter

password - dm1234


You base 64 encode digitalmatter:dm1234

Use this - https://www.base64encode.org/ or similar


So the result is  ZGlnaXRhbG1hdHRlcjpkbTEyMzQ=


And header would be as is shown above.


TCP 'standard' example 


<configuration> 

<appSettings> 

<add key="serverName" value="49.2.219.149"/> 

<add key="serverPort" value="8970"/> 

</appSettings>

</configuration>


Multi Example.


<configuration> 

<appSettings> 

<add key="connectors" value="52,447"/>

</appSettings>

</configuration>



To find the connector values, right click on the 'Edit' link in the connector screen of the connector, and select 'Inspect'. The console will appear on the right and a section of html will be highlighted with a ID number in the 'EditConnector(###)' tag.


Here are the list of our TG connectors to save time


TG(APAC01) - 390
TG(APAC02) - 391

TG(APAC03) - 419
TG(APAC04) - 421


TG(AMER01) - 496


TG(EMEA01) - 384

TG( EMEA02) - 385

TG( EMEA03) - 447

TG( EMEA04) - 470