Web (browser)

These classes and functions are available via the @transitive-sdk/utils-web npm package and are for use in the browser or other browser based front-ends.

Example

In this example we create a new web-component (custom element) from a React component using mqttSync to subscribe to some data and re-rendering it in real-time whenever it changes.

import React, { useEffect } from 'react';

import { createWebComponent, useTransitive, getLogger }
  from '@transitive-sdk/utils-web';

const log = getLogger('my-new-capability');
log.setLevel('debug');

// Get the name of the package we are part of. TR_PKG_NAME is set by esbuild.
const [scope, capabilityName] = TR_PKG_NAME.split('/');

const Device = ({jwt, id, host, ssl}) => {

  const { mqttSync, data, StatusComponent, prefixVersion } =
    useTransitive({ jwt, id, host, ssl,
      capability: TR_PKG_NAME,
      versionNS: TR_PKG_VERSION_NS
    });

  // once mqttSync is connected, subscribe to some topics
  useEffect(() => {
      if (!mqttSync) return;
      mqttSync.subscribe(`${prefixVersion}/device`);
      mqttSync.subscribe(`${prefixVersion}/cloud`);
    }, [mqttSync]);

  log.debug({prefixVersion, data, TR_PKG_NAME, TR_PKG_VERSION, TR_PKG_VERSION_NS});

  return <div>
    <StatusComponent />
    <pre>
      {/* Render the data. This updates automatically whenever data changes. */}
      {JSON.stringify(data, true, 2)}
    </pre>
  </div>;
};

createWebComponent(Device, `${capabilityName}-device`, ['jwt']);

reconnectPeriod

Implement dynamic backoff when we fail to connect.

ErrorBoundary

Extends React.Component

A simple error boundary. Usage:

 <ErrorBoundary message="Something went wrong">
   <SomeFlakyComponent />
 </ErrorBoundary>

Parameters

• props

CapabilityContextProvider

Context provider for capabilities. Use this to access the front-end API provided by some capabilities. Example:

 <CapabilityContextProvider jwt={jwt}>
   <MyROSComponent />
 </CapabilityContextProvider>

where jwt is a JWT for a capability that exposes a front-end API. Then use useContext in MyROSComponent to get the exposed data and functions, e.g.:

const MyROSComponent = () => {
  const { ready, subscribe, data } = useContext(CapabilityContext);
  // When ready, subscribe to the `/odom` topic in ROS1
  useEffect(() => { ready && subscribe(1, '/odom'); }, [ready]);
  return <pre>{JSON.stringify(data, true, 2)}</pre>;
}

Where ready, subscribe, and data are reactive variables and functions exposed by the capability of the provided JWT. In this example, the latest message from the subscribed ROS topics will be available in the capabilities namespace in data.

Parameters

• props object

  • props.children
  • props.jwt
  • props.host (optional, default undefined)
  • props.ssl (optional, default undefined)

Code

Reusable component for showing code

Parameters

• $0 Object

  • $0.children

createWebComponent

Create a WebComponent from the given react component and name that is reactive to all attributes. Used in web capabilities. Example:

createWebComponent(Diagnostics, 'health-monitoring-device', TR_PKG_VERSION);

Parameters

• Component
• name
• version (optional, default '0.0.0')
• options (optional, default {})

fetchJson

get or post (if body given) json

Parameters

• url
• callback
• options (optional, default {})

notifyListeners

set the returns for all listeners

Parameters

• args ...any

parseCookie

parse document cookies

Parameters

• str

TransitiveCapability

Dynamically load and use the Transitive web component specified in the JWT. Embedding Transitive components this way also enables the use of functional and object properties, which get lost when using the custom element (Web Component) because HTML attributes are strings. Example:

  <TransitiveCapability jwt={jwt}
    myconfig={{a: 1, b: 2}}
    onData={(data) => setData(data)}
    onclick={() => { console.log('custom click handler'); }}
  />

Always loads the capability specified in the JWT and will default to the main component for that JWT (-device or -fleet). To specify a secondary component offered by the capability specify component, e.g., to load webrtc-video-supervisor instead of webrtc-video-device, provide a device JWT for webrtc-video and use:

  <TransitiveCapability jwt={jwt}
    component='webrtc-video-supervisor'
    auto="true"
  />

Parameters

• $0 Object

  • $0.jwt
  • $0.host (optional, default 'transitiverobotics.com')
  • $0.ssl (optional, default true)
  • $0.config ...any

useCapability

Hook to load a Transitive capability. Besides loading the custom element, this hook also returns any functions and objects the component exports in loadedModule. Example:

  const {loaded, loadedModule} = useCapability({
    capability: '@transitive-robotics/terminal',
    name: 'mock-device',
    userId: 'user123',
    deviceId: 'd_mydevice123',
  });

Parameters

• $0 Object

  • $0.capability
  • $0.name
  • $0.userId
  • $0.deviceId
  • $0.host (optional, default 'transitiverobotics.com')
  • $0.ssl (optional, default true)
  • $0.appReact

useMqttSync

Hook for using MqttSync in React.

Parameters

• $0 Object

  • $0.jwt
  • $0.id
  • $0.mqttUrl
  • $0.appReact

Returns object An object {data, mqttSync, ready, StatusComponent, status} where: data is a reactive data source in React containing all the data received by mqttsync, mqttSync is the MqttSync object itself, ready indicates when mqttSync is ready to be used (connected and received successfully subscribed to mqtt system heartbeats)

useTopics

Subscribe to MqttSync topics using the provided JWT. This will automatically find which version of the capability named in the JWT is running on the device of the JWT and get the data for that version.

Example usage (with webrtc-video):

  const { agentStatus, topicData } = useTopics({ jwt, topics: [
    '/options/videoSource',
    '/stats/+/log/'
  ]});

Parameters

• options object An object containing: JWT: A list of subtopics of the capability named in the JWT. topics: A list of subtopics of the capability named in the JWT.

  • options.jwt
  • options.host (optional, default 'transitiverobotics.com')
  • options.ssl (optional, default true)
  • options.topics (optional, default [])
  • options.appReact

Returns object An object {data, mqttSync, ready, agentStatus, topicData} where: agentStatus is the status field of the running robot agent, including heartbeat and runningPackages, and topicData is the data for the selected topics of the capability

useTransitive

Hook for using Transitive in React. Connects to MQTT, establishes sync, and exposes reactive data state variable.

Parameters

• $0 Object

  • $0.jwt
  • $0.id
  • $0.capability
  • $0.versionNS
  • $0.appReact
  • $0.host (optional, default 'transitiverobotics.com')
  • $0.ssl (optional, default true)