This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

This module is a OPC-UA command and control proxy for Azure IoT written in C and intended to be hosted in an Edge Gateway built using the Azure IoT Gateway SDK.

It can tunnel binary channel streams (at this point TCP based streams only) at the application level, from a cloud service via one or more local network gateways to a server in the local network. It uses IoT Hub Methods as protocol layer and IoT Hub device registry as a name service provider, and only requires port 443 (outgoing) open to Azure.

This allows cloud OPC-UA applications to send and receive raw buffers to and from IoT server devices that are accessible on the local gateway network. Using the API one can quickly implement command and control scenarios from a cloud application without providing edge command/control translation.

Visit http://azure.com/iotdev to learn more about developing applications for Azure IoT.

Branch	Status
master

The Azure IoT Field Gateway Proxy module depends on several components which are included as submodules. Hence, if you did not specify the --recursive option when using git clone to clone this repo, you need to first run git submodule update --init in a console or terminal window before continuing...

• The Proxy module was tested on Ubuntu 16.04 and Alpine Linux 3.5, but can be built on a variety of Linux flavors. Check out the Dockerfile folder to find examples on how to set up your specific distribution. If you do not find yours in the folder, consider contributing a Dockerfile target to this project.
• To build the dotnet samples and API, follow the instructions here to install .net Core on Linux.
• Run bash <repo-root>/bld/build.sh. After a successful build, all proxy binaries can be found under the /build/cmake/bin folder.
• (Optional) To install run the usual make install in directory build/cmake/Release or build/cmake/Debug. For a test install to /tmp/azure you could use for example the following: make -C <repo-root>/build/cmake/Debug DESTDIR=/tmp/azure install. Then run the proxy: LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/tmp/azure/usr/local/lib /tmp/azure/usr/local/bin/proxyd --help

Run the build script with the --help option to see all configuration options available.

The Proxy module was successfully built and tested on Windows 10 with Visual Studio 2017.

• Install Visual Studio 2017.
• Install CMAKE (3.7 or later) from here.
• Run <repo-root>\bld\build.cmd. After a successful build, all proxy binaries can be found under the \build\cmake<platform>\bin folder.

Run the build script with the --help option to see all configuration options available.

The current version of the Proxy module is targeted at the Azure IoT Gateway SDK 2016-12-16 version.

Use the following command line to clone the compatible version Azure IoT Gateway SDK, then follow the build instructions included:

git clone -b "2016-12-16" --recursive https://github.com/Azure/azure-iot-gateway-sdk.git

All samples require an Azure IoT Hub to be provisioned in your Azure Subscription and access to the iothubowner policy connection string.

For more information, see

• Set up IoT Hub describes how to configure your Azure IoT Hub service.
• Manage IoT Hub describes how to provision devices in your Azure IoT Hub service.

For simplicity, the default Iot Hub provider used by most of the samples reads the connection string from the _HUB_CS environment variables when not provided programmatically.

While the Proxy module can be hosted by a Gateway built using the Field gateway SDK, the proxyd executable is an alternative host which can be configured from the command line. An IoT Hub connection string can be provided via the -c, -C or -s command line arguments or through the _HUB_CS environment variable (which allows you to run the host without any command line arguments).

If the iothubowner policy connection string is provided, it will automatically create a proxy entry in your Iot Hub using the host name of the machine it is running on, and then wait and listen for requests. Use the -D option to persist the registration information locally.

For example, to install a proxy, you can run proxy -i -C iothubowner.txt -D config.db which will add the device to the config.db file, and optionally safe the key in a platform specific secure location. You can then run proxy -D config.db to start the proxy. The proxy will read the connection string from config.db, connect to Azure, and wait for requests.

Run the proxyd executable with --help command line switch to see all available options.

A docker container that contains the proxy module host can be built and run directly from github. If you have not done so already, install docker on your machine, then in a terminal or console window, run:

docker build -t <tag> https://github.com/Azure/iot-gateway-proxy
docker run <tag> <commandlineargs>

The following samples are included and demonstrate how to use the API:

• An OPC UA client that shows how the OPC-Foundation reference stack transport adapter can provide OPC-UA relay access to OPC UA servers in a Proxy network.

• A Simple TCP/IP services client that demonstrates the different API calls.

The Azure IoT Field Gateway Proxy module is licensed under the MIT License.
You can find license information for all third party dependencies here. Note that not all of these dependencies need to be utilized, depending on your build configuration, or your choice of platform.

If you are having issues compiling or using the code in this project please feel free to log an issue in the issues section of this project. For other issues, such as Connectivity issues or problems with the portal, or issues using the Azure IoT Hub service the Microsoft Customer Support team will try and help out on a best effort basis. To engage Microsoft support, you can create a support ticket directly from the Azure portal.

Contributions are welcome, in particular in the following areas

• RTOS, OSX and Unix PAL ports and testing
• None IP streams, e.g. Pipe and Serial port remoting
• API bindings, e.g. node.js or Java