Documentation Hook API

Managing Devices

useDeviceHasAcceptableConnection

The useDeviceHasAcceptableConnection hook returns whether a device has any acceptable connections active.

import { useDeviceHasAcceptableConnection } from '@electricui/components-core'
function DeviceConnectionHealthIndicator() {
  const connectionAcceptable = useDeviceHasAcceptableConnection()
 
  if (connectionAcceptable) {
    // Draw a green tick, etc
    return <div>The connection is acceptable!</div>
  }
 
  return <div>The connection is unacceptable.</div>
}

See the docs on connection acceptability for information on how this is calculated.

useDeviceManager

This hook is widely used internally to build most of our public facing hooks.

In general, we recommend using other public facing hooks to achieve narrower specific goals, such as useDeviceHandshakeState or useDeviceConnectionState.

import { useDeviceManager } from '@electricui/components-core'

Get in touch if you think you need to use this hook.

useDeviceID

The useDeviceID hook returns the DeviceID of the current context.

The majority of the hooks in Electric UI that need device specific state use this hook internally.

import { useDeviceID } from '@electricui/components-core'
function WhatDeviceIDIsThis() {
  const deviceID = useDeviceID()
 
  return <div>deviceID: {deviceID}</div>
}

useDeviceIDList

The useDeviceIDList hook returns all the DeviceIDs currently available.

import { useDeviceIDList } from '@electricui/components-core'
import { DeviceID } from '@electricui/core'
interface DeviceInformationProps {
  deviceID: DeviceID
}
 
function DeviceInformation(props: DeviceInformationProps) {
  const name = useDeviceMetadataKey('name', props.deviceID)
 
  return (
    <div>
      deviceID: {props.deviceID} has name {name}
    </div>
  )
}
 
function WhatDeviceIDIsThis() {
  const deviceIDs = useDeviceIDList()
 
  return (
    <div>
      {deviceIDs.map(deviceID => (
        <DeviceInformation key={deviceID} deviceID={deviceID} />
      ))}
    </div>
  )
}

usePollForDevices

The usePollForDevices hook returns an object that contains a poll function to poll for the specified period of time, and a polling state to indicate if it is currently polling.

This example displays a simple connection screen.

import { usePollForDevices } from '@electricui/components-core'
interface DeviceCardProps {
  deviceID: DeviceID
}
 
function DeviceCard(props: DeviceCardProps) {
  const name = useDeviceMetadataKey('name', props.deviceID)
  const connect = useDeviceConnect(props.deviceID)
  const disconnect = useDeviceDisconnect(props.deviceID)
  const connectionRequested = useDeviceConnectionRequested(props.deviceID)
 
  return (
    <div>
      Device {name} -
      <button onClick={connectionRequested ? disconnect : connect}>
        {connectionRequested ? 'Disconnect' : 'Connect'}
      </button>
    </div>
  )
}
 
function ConnectionPage() {
  const deviceIDs = useDeviceIDList()
  const { polling, poll } = usePollForDevices(5000) // poll for 5 seconds
 
  return (
    <div>
      {deviceIDs.map(deviceID => (
        <DeviceCard key={deviceID} deviceID={deviceID} />
      ))}
 
      <button onClick={poll} disabled={polling}>
        Poll for devices
      </button>
    </div>
  )
}

useDeviceConnect

The useDeviceConnect hook returns a function that connects to the device specified by the device context or the deviceID argument.

import { usePollForDevices } from '@electricui/components-core'

Read the usePollForDevices example for its use.

useDeviceDisconnect

The useDeviceDisconnect hook returns a function that disconnects from the device specified by the device context or the deviceID argument.

import { useDeviceDisconnect } from '@electricui/components-core'

Read the usePollForDevices example for its use.

useDeviceConnectionRequested

The useDeviceConnectionRequested hook returns if the specified device currently has a connection requested.

import { useDeviceConnectionRequested } from '@electricui/components-core'

Read the usePollForDevices example for its use.

useDeviceMetadataKey

The useDeviceMetadataKey hook returns a piece of the device metadata denoted by the metadata key.

import { useDeviceMetadataKey } from '@electricui/components-core'

Read the usePollForDevices example for its use.

useDeviceConnectionHashes

The useDeviceConnectionHashes hook returns an array of the current device's connection hashes.

interface ConnectionCardProps {
  connectionHash: string
}
 
function ConnectionCard(props: ConnectionCardProps) {
  const transportKey = useConnectionTransportKey(props.connectionHash)
 
  return (
    <div>
      Connection hash {props.connectionHash} has transport key {transportKey}
    </div>
  )
}
 
function DeviceConnections() {
  const connectionHashes = useDeviceConnectionHashes()
 
  return (
    <div>
      {connectionHashes.map(connectionHash => (
        <ConnectionCard key={connectionHash} connectionHash={connectionHash} />
      ))}
    </div>
  )
}

useDeviceConnectionState

The useDeviceConnectionState hook returns the aggregate connection status of the device. As a device may have multiple connections, the connection status reflects the 'most impactful' state.

For example, the CONNECTING state applies if no links are connected, with at least one link currently attempting to connect. If an existing link(s) are already CONNECTED, then the aggregated state is still CONNECTED while the new connections are made or closed.

import { useDeviceConnectionState } from '@electricui/components-core'
import { CONNECTION_STATE } from '@electricui/core'
function DeviceConnectionState() {
  const connectionState = useDeviceConnectionState()
 
  switch (connectionState) {
    case CONNECTION_STATE.DISCONNECTED:
      return <div>Device is disconnected</div>
 
    case CONNECTION_STATE.CONNECTING:
      return <div>Device is connecting</div>
 
    case CONNECTION_STATE.DISCONNECTING:
      return <div>Device is disconnecting</div>
 
    case CONNECTION_STATE.CONNECTED:
      return <div>Device is connected</div>
 
    default:
      throw new Error('Connection state is unknown')
  }
}

useDeviceHandshakeProgressIDs

The useDeviceHandshakeProgressIDs hook returns an array of all the handshake progress IDs for the device in context.

This example displays a simple handshake loading screen.

import { useDeviceHandshakeProgressIDs, useDeviceHandshakeProgress } from '@electricui/components-core'
import { ProgressBar } from '@blueprintjs/core'
interface HandshakeCardProps {
  handshakeID: string
}
 
function HandshakeCard(props: HandshakeCardProps) {
  const progress = useDeviceHandshakeProgress(props.handshakeID)
 
  if (!progress) return null
 
  const { currentTask, complete, total } = progress
 
  return (
    <div>
      <ProgressBar value={total === 0 ? 0 : complete / total} />
      {currentTask}
    </div>
  )
}
 
function DeviceLoadingScreen() {
  const handshakeIDs = useDeviceHandshakeProgressIDs()
 
  return (
    <div>
      {handshakeIDs.map(handshakeID => (
        <HandshakeCard key={handshakeID} handshakeID={handshakeID} />
      ))}
    </div>
  )
}

useDeviceHandshakeProgress

The useDeviceHandshakeProgress hook returns a handshake progress object given a handshakeID. It uses the current device context or optionally takes a deviceID.

import { useDeviceHandshakeProgress } from '@electricui/components-core'

Read the useDeviceHandshakeProgressIDs example for its use.

useDeviceHandshakeState

The useDeviceHandshakeState hook returns the HANDSHAKE_STATE of the device.

import { useDeviceHandshakeState } from '@electricui/components-core'
import { HANDSHAKE_STATE } from '@electricui/core'
function DeviceHandshakeState() {
  const handshakeState = useDeviceHandshakeState()
 
  switch (handshakeState) {
    case HANDSHAKE_STATE.NOT_STARTED:
      return <div>Handshake has not started</div>
 
    case HANDSHAKE_STATE.IN_PROGRESS:
      return <div>Handshake is in progress</div>
 
    case HANDSHAKE_STATE.COMPLETE:
      return <div>Handshake has completed</div>
 
    case HANDSHAKE_STATE.FAILED:
      return <div>Handshake has failed</div>
 
    case HANDSHAKE_STATE.CANCELLED:
      return <div>Handshake has been cancelled</div>
 
    default:
      throw new Error('Handshake state is unknown')
  }
}

useDeviceIDByMetadata

The useDeviceIDByMetadata hook retrieves a deviceID using a subset of metadata.

Its main use is to render a sub-device's UI inside the context of another device's UI.

import {
  useDeviceIDByMetadata,
  DeviceIDContextProvider,
} from '@electricui/components-core'
import { Printer } from '@electricui/components-desktop'
function CameraTriggerInformation() {
  return (
    <>
      <p>
        ISO: <Printer accessor="iso" />
      </p>
      <p>
        Shutter: <Printer accessor="shutter" />
      </p>
      <p>
        Aperture: <Printer accessor="aperture" />
      </p>
    </>
  )
}
 
function CameraTrigger() {
  const cameraTriggerDeviceID = useDeviceIDByMetadata({
    cameraTrigger: true,
  })!
 
  return (
    <DeviceIDContextProvider deviceID={cameraTriggerDeviceID}>
      <CameraTriggerInformation />
    </DeviceIDContextProvider>
  )
}

useDeviceIDByTransportKey

The useDeviceIDByTransportKey hook retrieves a deviceID from a provided transport key.

import { useDeviceIDByTransportKey } from '@electricui/components-core'

useDeviceIDByConnectionHash

The useDeviceIDByConnectionHash hook retrieves a deviceID matching a connection hash.

import { useDeviceIDByConnectionHash } from '@electricui/components-core'