Creates an instance of MasterController
, a subclass of
MasterControlClient
.
configuration options for the MasterControlClient
configuration options for the MasterController
Readonly
clientGets the client's unique client ID to be used for logging purposes, etc.
Readonly
debugGets a debugger function associated with this client instance.
Used to log informational, debug, and error messages. The first argument
is a formatter string with printf-style formatting supporting the
following directives: %O
(object multi-line), %o
(object
single-line), %s
(string), %d
(number), %j
(JSON), %%
(escape).
To turn on debug output for this library, set the DEBUG
environment
variable to vda-5050:*
. To enable low-level MQTT debugging, use
vda-5050:*,mqttjs*
. Use *
to debug all debug-enabled modules in your
application.
Gets the client configuration options as a readonly object.
Gets the master controller configuration options as a readonly object with default values filled in for options not specified.
Protected
isDetermines whether the client has been started.
true if client has been started; false otherwise
Gets the semantic version of the VDA 5050 protocol this implementation conforms to.
a string in the format
"<major-version-number>.<minor-version-number>.<patch-version-number>"
Assign an order (including an order update or a stitching order) to be executed by an AGV and report back changes in the order's execution state.
An assigned order must fulfil the following characteristics to be executable by an AGV:
If a stitching order is assigned, the event handler callbacks of the previously assigned order are just triggered for State events still emitted on the previous order. Any State events triggered on the new order are emitted on the event handler callbacks of the newly assigned stitching order. Note that Node, Edge, and Action objects passed by these event handlers may refer to the order context of the previous order.
Any order that has the same AGV target and the same orderId and
orderUpdateId as a currently active order will be discarded, resolving
undefined
. The given event handler callbacks will never be invoked.
Instead, the previously registered callbacks continue to be invoked.
Any Node, Edge, Action, and Order object passed to order event handler callbacks is guaranteed to be reference equal to the original object passed to this method. However, AgvId objects passed are never reference equal, but value equal.
a promise that resolves the order object with header when
published successfully or undefined
when order has been discarded, and
rejects if order is not valid or controller has not been started
identifies the target AGV
the headerless order to be executed
callbacks that report order-related events
Protected
getGets the VDA 5050 communication topic with an associated object to be registered as a last will message.
Returns undefined
if no last will should be registered (default). To be
overridden by subclasses.
a last will object with a topic, a headerless object, and a
retain indicator, or undefined
Protected
getGets the semantic version of the VDA 5050 protocol this implementation conforms to.
To be overridden by subclasses that provide VDA 5050 extensions. The
default version returned by the base method is the standard VDA 5050
protocol version this Client
class implements.
a string in the format
"<major-version-number>.<minor-version-number>.<patch-version-number>"
Gets the most recently tracked connection state of a given AGV.
the latest connection state with the timestamp of the latest
state change or undefined
if the state is not yet known.
identity of the AGV
Gets the most recently tracked connection states of all tracked AGVs.
an array of objects with AGV identifier, the latest connection state and the timestamp of the latest state change.
Initiate instant actions to be executed by an AGV and report back changes on the execution state of the actions.
Any Action and AgvId object passed to instant action event handler callbacks is guaranteed to be reference equal to the original object passed to this method.
a promise that resolves an instant actions object with header when published successfully and rejects if given instant actions object is not valid or controller has not been started
identifies the target AGV
a headerless instant actions object
callback that reports instant action related events
Protected
onProtected
onInvoked before the client disconnects actively.
To be overridden by subclasses that need to perform additional synchronous or asynchronous actions, such as publishing a message before the client disconnects actively.
The base method does nothing.
Publishes the given VDA 5050 core or extension object on the given VDA 5050 communication topic related to the given AGV subject.
The AgvId
subject is used to automatically fill in header properties of
the object to be published. Each of its properties must specify a
non-empty string and must be valid as an MQTT topic level.
On successful publication, this async function resolves a promise
containing a copy of the given headerless object including all header
properties as it has been published. If the publication is dropped
according to the dropIfOffline
publish option, the promise resolves
with an undefined
value.
a promise that resolves the published object if publication
succeeds or undefined
if message should be dropped while offline
synchronously if client is not started, if topic or subject is not valid, if object validation fails
the VDA 5050 communication topic to publish on
identity of the AGV which is related to this publication
a VDA 5050 core or extension object without header properties
Optional
options: ClientPublishOptionsclient publish options (optional)
Protected
publishPublishes the given VDA 5050 core or extension object on the given VDA 5050 communication topic related to the given AGV subject.
The AgvId
subject is used to automatically fill in header properties of
the object to be published. Each of its properties must specify a
non-empty string and must be valid as an MQTT topic level.
On successful publication, this async function resolves a promise
containing a copy of the given headerless object including all header
properties as it has been published. If the publication is dropped
according to the dropIfOffline
publish option, the promise resolves
with an undefined
value.
a promise that resolves the published object if publication
succeeds or undefined
if message should be dropped while offline
synchronously if client is not started, if topic or subject is not valid, if object validation fails
the VDA 5050 communication topic to publish on
identity of the AGV which is related to this publication
a VDA 5050 core or extension object without header properties
Optional
options: ClientPublishOptionsclient publish options (optional)
Register a callback function invoked whenever the client's connection state changes.
Upon registration, the given callback is invoked immediately with the current connection state.
You can only register one callback per client; any previously registered callback is discarded.
a callback function
Registers a custom VDA 5050 communication topic with a validator function to check structure and constraints of corresponding extension objects at runtime.
The asInbound
and asOutbound
parameters indicate whether the
registered extension topic should be allowed for inbound communication
and/or outbound communication. If inbound communication is not allowed,
subscribing to the topic will fail. Likewise, if outbound communication
is not allowed, publishing on the topic will fail.
The validator function is invoked on inbound and/or outbound messages
with a registered extension topic according to the client option
topicObjectValidation
.
The validator function should throw a TypeError
synchronously if the
passed extension object structure does not conform to the passed
extension topic and the direction of the message (inbound, outbound).
If the given topic is already registered, its registration will be overridden with the new parameters.
Use the function createValidators
in the create-validators
script
provided by this package to generate JS validation functions for your
custom JSON schemas. Use these functions in this method override.
a custom VDA 5050 communication topic
whether topic should be allowed on inbound communication
whether topic should be allowed on outbound communication
a function that validates message objects against the given extension topic
Protected
resetStarts client interaction by connecting to the configured MQTT broker.
If client is already started, this operation is a noop.
Always await this operation before invoking other operations on this client instance.
a promise resolved when client is initially connected, and rejected when connection fails
Stops client interaction by disconnecting from the MQTT broker and cleaning up all active subscriptions and registered extension topics.
If client is not started, this operation is a noop.
Always await this operation before invoking other operations on this
client instance, such as start
.
After the client is stopped any publish, subscribe, and unsubscribe operations will throw an error until the client is restarted.
a promise resolved when client is disconnected from the underlying MQTT transport.
Subscribes to the given VDA 5050 communication topic for the given AGV subject and registers a handler function to be invoked when matching inbound publication messages are received by this client.
In the given partial AgvId
subject, any property must either specify a
non-empty string which is valid as an MQTT topic level or be undefined
or excluded, to support wildcard subscriptions by control clients.
Otherwise, an error is thrown.
If multiple subscription handlers are registered for a given subscription, they are invoked synchronously in series, one after the other, but in arbitrary order.
A subscription handler should never perform long-lasting synchronous operations as it blocks processing of other handlers and incoming messages.
A subscription handler may also perform asynchronous operations but these are are not awaited and not synchronized with the invocation of subsequent handlers.
A subscription handler is responsible for catching any errors. Uncaught errors result in "Uncaught Error" or "Unhandled Promise Rejection" reported by the runtime.
Take care to invoke Client.unsubscribe
method on any subscription ID
that is no longer needed by the application to clean up the
subscription's handler function and to reduce network traffic.
Unsubscribing in a handler function is also possible; use the
corresponding subscription id passed as argument. If you want to keep a
subscription for the lifetime of the client, there is no need to
explicitely unsubscribe it before stopping the client.
a promise that resolves a unique subscription ID when subscription is set up successfully
synchronously if client is not started, if topic or subject is not valid
the VDA 5050 communication topic to subscribe to
identity of the AGV(s) which are related to this subscription
a function invoked on any inbound message matching the subscription
Protected
subscribeSubscribes to the given VDA 5050 communication topic for the given AGV subject and registers a handler function to be invoked when matching inbound publication messages are received by this client.
In the given partial AgvId
subject, any property must either specify a
non-empty string which is valid as an MQTT topic level or be undefined
or excluded, to support wildcard subscriptions by control clients.
Otherwise, an error is thrown.
If multiple subscription handlers are registered for a given subscription, they are invoked synchronously in series, one after the other, but in arbitrary order.
A subscription handler should never perform long-lasting synchronous operations as it blocks processing of other handlers and incoming messages.
A subscription handler may also perform asynchronous operations but these are are not awaited and not synchronized with the invocation of other handlers.
A subscription handler is responsible for catching any errors. Uncaught errors result in "Uncaught Error" or "Unhandled Promise Rejection" reported by the runtime.
Take care to invoke Client.unsubscribe
method on any subscription ID
that is no longer needed by the application to clean up the
subscription's handler function and to reduce network traffic.
Unsubscribing in a handler function is also possible; use the
corresponding subscription id passed as argument. If you want to keep a
subscription for the lifetime of the client, there is no need to
explicitely unsubscribe it before stopping the client.
a promise that resolves a unique subscription ID when subscription is set up successfully
synchronously if client is not started, if topic or subject is not valid
the VDA 5050 communication topic to subscribe to
identity of the AGV(s) which are related to this subscription
a function invoked on any inbound message matching the subscription
Tracks the lifecycle of all AGVs in the driverless transport system by emitting connection state changes on the given handler function.
You can invoke this method before or after the client is started. If already known, the latest connection states of AGVs are immediately dispatched synchronously on the given handler.
a function invoked whenever the connection state of any tracked AGV changes. The function is passed the identity of the AGV, its connection state and its timestamp.
Unsubscribes the subscription issued for the given subscription ID.
The subscription's handler function will be cleaned up and no longer invoked. If there are no other active subscriptions on the associated VDA 5050 topic, the corresponding MQTT topic will also be unsubscribed to prevent unnecessary network traffic.
If the given subscription ID is already unsubscribed, it is silently ignored.
a promise that resolves on successful unsubscription
synchronously if client is not started
the subscription ID related to an issued subscription
Protected
validatePerforms a runtime validation check of the given AGV identity to be used as subject of a subscription or publication.
For publications, all AgvId
properties must be specified and valid. For
subscriptions, any property may be omitted, but existing properties must
have valid values.
a TypeError
if validation check fails
(partial) identity of AGV
whether to validate as a subscription or publication subject
Protected
validateValidate standard VDA 505 topics at runtime with respect to the direction of information exchange. A control client can only publish on certain topics and only subscribe on certain topics.
Protected
validatePerforms a runtime validation check of a VDA 5050 core or extension object with respect to a given VDA 5050 topic.
a TypeError
if validation check fails
a VDA 5050 communication topic
a VDA 5050 core or extension object with header properties
Generated using TypeDoc
Implements the common control logic and interaction flows on the coordination plane (master control) as defined by the VDA 5050 specification. This includes assigning orders and initiating instant actions, as well as reporting back their execution state.
Together with its counterpart on the vehicle plane, it builds a high-level abstraction layer of the complex control logic defined in the VDA 5050 specification.
Remarks
This VDA 5050 implementation requires Node, Edge, and Action objects to specify unique IDs. You should always use the
createUuid
function to create such an ID as it generates globally unique IDs.This VDA 5050 implementation requires order rejection errors related to non-supported or non-executable node or edge actions to report an error with
errorType: "orderError"
, whereas order action errors reported for failed actions must specify a different error type (e.g.errorType: "orderActionError"
) to make them distinguishable.