useAdapterEndpoint

A React hook designed to connect to an Odin Control Endpoint or adapter.

Usage allows for GET and PUT requests to be automated, as well as periodic GET calls for adapters that have constantly updating data that needs to be reflected in the GUI. This hook can then be passed to other components as a Property, allowing multiple components in your GUI to utilise the same endpoint, and will reflect changes potentially made by other components.

This hook maintains a local copy of the data it gets from the adapter, which can then be displayed in the GUI elements. When done this way, any data displayed will automatically update if and when the local copy within the hook is updated. It is important to note that none of the HTTP methods provided by this Endpoint automatically merge the response into the Endpoints local copy of the data.

This hook was designed with the intention of connecting to a single adapter. Therefore, if multiple adapters exist in a system that should be connected to, you should use one hook per adapter.

Tip

In Typescript, the hook can be passed an interface defining the layout and data types of the returned Parameter tree structure. This then means any component using values from the endpoint's data object should know what values are available and what their types are.

Note

In many standard GUI Apps, it is unlikely that any of the methods provided by the Endpoint will need to be used. Mostly, the endpoint will be passed to other components, which will then utilize these methods.

The Example react app within this Git Repo has a page designed to show the several potential use cases for the AdapterEndpoint hook.

Properties

import { useAdapterEndpoint } from 'odin-react';

Name	Type	Default	Description
adapter	string		Required The name of the Adapter within Odin Control that this endpoint should send requests to.
endpoint_url	string		The URL of the Odin Control Instance, including IP and port address. Recommended to set in an importable .env.local file to avoid publishing IP addresses onto github. eg http://192.168.0.1:1234
interval	number		If set to a number of milliseconds, the endpoint will periodically send a GET request to the adapter at the specified regularity.
timeout	number		If set, any requests made will timeout after this many milliseconds and return a HTTP error code. This timeout is done in waiting for a response, so there is a possibility any PUT requests will still enact change to the adapter.
api_version	string	'0.1'	The API version used within the adapter's URI. Will not need to be modified from default.

Return Objects and Functions

Objects and Variables

Name	Type	Description
data	T extends ParamTree	ReadOnly A Dictionary style object representing the entire parameter tree of the Adapter. In Typescript, an interface T can be provided to the AdapterEndpoint, which defines the expected shape and types of that parameter tree.
metadata	ParamTree	ReadOnly A Dictionary style object representing the parameter tree of the Adapter, with metadata. If the adapter has not implemented metadata requests in it's GET function, this will be identical to the data object.
error	Error | null	If an error occurs during a HTTP request, it will be represented by this value.
loading	boolean	True if the endpoint is awaiting a HTTP response, otherwise False. Used to disable components that would try and perform further HTTP requests whilst the endpoint is busy
updateFlag	Symbol	If the endpoint's data object changes, due to updates from a PUT request or a GET request, this flag will refresh. This can then be used in React hook dependency arrays, such as the dependency array of a useEffect hook. This is done because objects, like data, cannot be checked for differences in the way React requires for those arrays.

Functions

Name	Signature	Description	Parameters	Return
get	async <T>(param_path: string, config: {wants_metadata: boolean, responseType: Axios.ResponseType}) => Promise<T>	Performs a HTTP GET request at the specified path, and returns the value. By default, the value is returned as a JSON object. 🆕Typescript: If T is specified, returns it as the specified type (for instance, a Blob object if an image is requested).	🆕 T: The Typescript Type expected of the returned value. Defaults to a JSON like object. param_path: The path on the adapter to request. Defaults to an empty string. config: an object with two optional values. wants_metadata requests the metadata with the value from the Adapter. responseType tells the HTTP request the type of the response expected. Defaults to JSON.	A Promise whose value is the data requested from the Adapter. 🆕Typescript: If T and the config.responseType are specified, this value will be as requested. It defaults to JSON
put	async (data: ParamTree, param_path: string) => Promise<ParamTree>	Performs a HTTP PUT request at the specified path to modify the specified parameter(s).	data: a JSON style object, with one or more key/value pairs, that represent the parameter name and the value to change it to. param_path: The path on the adapter to send the request. Defaults to an empty string	A Promise, whose value is the value of the response from the PUT request
post	async (data: ParamTree, param_path: string) => Promise<ParamTree>	Performs a HTTP POST request at the specified path, to modify the specified parameter(s). Not many Adapter's implement this method.	data: a JSON style object, with one or more key/value pairs, that represent the parameter name and the value to change it to. param_path: The path on the adapter to send the request. Defaults to an empty string	A Promise, whose value is the value of the response from the POST request
remove	async (param_path: string) => Promise<NodeJSON>	Performs a HTTP DELETE request at the specified path, to delete some part of the Adapter's parameter tree. Not many Adapter's implement this method.	param_path: The path on the adapter to send the request. Defaults to an empty string	A Promise, whose value is the value of the response from the DELETE request
refreshData	() => void	Perform a top level GET request from the adapter, and merge the response data into the local data object.
mergeData	(newData: ParamTree, param_path: string)	Merge the data in the newData object into the local data tree, at the path specified	newData: A JSON style object containing data to be merged into the local data object param_path: The path within the nested data structure to the location where the new data needs to be merged.

Example

// Creates an endpoint that will send a GET request to the following path once a second:
// http://localhost:8888/api/0.1/adapter

//interface defines the expected shape of the Adapter's ParamTree

interface endpointData_t extends ParamTree {
    string_val: string;
    num_val: number;
    dict_vals : {
        dict_num: number;
        dict_string: string;
    }
}

const exampleEndpoint = useAdapterEndpoint<endpointData_t>("adapter", "http://localhost:8888", 1000);