Getting Started

Bootstrap your React app:

npx create-react-app subioto-example

Add the subioto-ui-react dependency:

yarn add subioto-ui-react

Replace the App.js with:

import './App.css';
import { SubiotoGauge, SubiotoContext, initSubioto } from "subioto-ui-react";

const SUBIOTO_URL = 'https://subioto-xyz.westeurope.azurecontainer.io';
const ROOT_TOKEN_FOR_DEVELOPMENT_ONLY = "fewifewoifewiofweoifew";

const subioto = initSubioto(SUBIOTO_URL, null, ROOT_TOKEN_FOR_DEVELOPMENT_ONLY);

function App() {

  return (
    <div className="App">
      <SubiotoContext.Provider value={subioto}>
        <SubiotoGauge
          deviceId="somedevice"
          telemetry="temperature"
          maxValue={40.0}
        />
      </SubiotoContext.Provider>
    </div>
  );
}

export default App;

Each time the telemetry value temperature arrives from device somedevice the gauge will be updated.

Usage

Initialization

You initialize Subioto using the initSubioto method. Your have to pass the base URL of your Subioto instance, and a function that forwards data access request of the various Subioto client components to your custom authentication backend. In order to authenticate the request to your authentication backend and to identify the current user, you can use whatever mechanism your application uses. Your custom backend must determine if the access request is granted or denied. If the request is granted, you must use the subioto-admin SDK (or a REST request against the Subioto admin API) in order to let Subioto know that the client should be subscribed to the requested data.

const CUSTOM_AUTH_BACKEND = 'https://your-custom-auth-backend';
const SUBIOTO_URL = 'https://subioto-xyz.westeurope.azurecontainer.io';

const subioto = initSubioto(SUBIOTO_URL, localAccessRequest => {
  // Put the call to your custom auth backend in here. Your backend could be an Azure function, a container, etc.
  // Use your own authentication scheme (Bearer token, basic auth, etc). The request below is just an example.
  return axios.put(CUSTOM_AUTH_BACKEND, localAccessRequest, {
    headers: {
      Authorization: `Bearer ${yourBearerTokenInYourApplication}`
    }
  })
});

If you do not care about fine-grained authentication yet, you can use root tokens that you can retrieve from the Subioto Admin UI in the Azure Portal.

const SUBIOTO_URL = 'https://subioto-xyz.westeurope.azurecontainer.io';
const ROOT_TOKEN_FOR_DEVELOPMENT_ONLY = "fewifewoifewiofweoifew";

const subioto = initSubioto(SUBIOTO_URL, null, ROOT_TOKEN_FOR_DEVELOPMENT_ONLY);

Subioto will then allow access to all available data.

WARNING: Under no circumstances should you use this approach in production, as anyone that can access your UI will have complete access to all data received from IoT Hub and will also be able to invoke direct methods.

Context

Define a Subioto Context to be able to use hooks and UI components deeper in the DOM tree. You have to pass the subioto instance returned by the initSubioto method.

<SubiotoContext.Provider value={subioto}>
  ...
</SubiotoContext.Provider>

Hooks

In order to access telemetry values from your devices, you can use the useTelemetry hook. Example:

export const MyComponent = props => {
  const temperature = useTelemetry("somedevice", "temperature");

  return (
    <p>
      Current temperature: {temperature}
    </p>
  );
}

The value will initially be null, but is continuously updated by incoming values.

To subscribe to updates of the Device Twin, use the useDeviceTwin hook. Example:

export const MyComponent = props => {
  const deviceTwin = useDeviceTwin("somedevice");

  return (
    <p>
      {deviceTwin && JSON.stringify(deviceTwin)}
    </p>
  );
}

Use the useDirectMethod hook to get a Javascript function that - when called - will execute the direct method on the device:

export const MyComponent = props => {
  const resetDevice = useDirectMethod("somedevice", {
    methodName: 'SetTelemetryInterval',
    payload: 10
  });

  return (
    <button onClick={resetDevice}>
      Update telemetry interval on device
    </button>
  );
}

UI Components

Instead of using the low-level hooks, you can also use read-made UI components that get their data live from Subioto.

Gauge