=================
Asset States
=================

You can use the :func:`AssetApi<artificial.client.assetapi.v1.assetapi.AssetApi>` to control the appearance of assets in your Digital Twin. There are 3 attributes that control the appearance of an asset:

- :coderef:`color`
- :coderef:`ops_state <ops-state>`
- :coderef:`assistance_state <assistance-state>`

We'll go through each of these in detail.


.. _asset-states-color:

``color``
---------
This attribute should be used if you would like to change the base color of an asset. Typically, this is used to change the asset to match what color the equipment is in real life. For example, if you have a red 96-well plate, you would set the color to ``#ff0000``.

.. code-block:: python

    @action()
    async def create_assets(self, actx: ActionExecutionContext, loading_config_id: str) -> t.List[str]:
        assets = await self.artificial_api.asset_api_v1.fetch_loading_config(actx=actx, load_config_id=loading_config_id)
        return await self.artificial_api.asset_api_v1.create(actx=actx, assets=assets, color="#ff0000")

Color is superseded by asset states, which can be set using the fields below.


.. _asset_states_ops_state:

``ops_state``
-------------

This attribute should be used to set the state of the asset; the Digital Twin will update the color and animation of the asset based on the state.
For example, if you have a piece of equipment that is in use and running, you would set the ``ops_state`` to ``ASSET_OPS_STATE_VALUE_RUNNING``.
This will change the color of the asset to the color and animation that is associated with the Running state.

.. code-block:: python

    from artificial.api.alab.asset.asset_state_pb2 import AssetState

    @action()
    async def set_running(self, actx: ActionExecutionContext, asset_id: str) -> t.List[str]:
        self.artificial_api.asset_api_v1.update(
            actx=actx, updates=[Asset.Update(id=asset_id, ops_state=AssetState.ASSET_OPS_STATE_VALUE_RUNNING)]
        )

Valid states are:

``ASSET_OPS_STATE_VALUE_UNKNOWN`` (Light gray, no animation)

``ASSET_OPS_STATE_VALUE_OFFLINE`` (Dark gray, no animation)

``ASSET_OPS_STATE_VALUE_GETTING_READY`` (Dark Gray, no animation)

``ASSET_OPS_STATE_VALUE_READY`` (Light gray, no animation)

``ASSET_OPS_STATE_VALUE_ERROR`` (Red, animated)

``ASSET_OPS_STATE_VALUE_RUNNING`` (Blue, animated)

``ASSET_OPS_STATE_VALUE_RESUMING`` (Blue, no animation)

``ASSET_OPS_STATE_VALUE_PAUSING`` (Blue, animated)

``ASSET_OPS_STATE_VALUE_PAUSED`` (Dark Blue, no animation)

``ASSET_OPS_STATE_VALUE_CANCELING`` (Red, animated)

``ASSET_OPS_STATE_VALUE_CANCELED`` (Red, no animation)

.. _asset_states_assistance_state:

``assistance_state``
--------------------
This attribute is used to set whether the asset is in need of manual intervention, e.g. for an Assistant. For example, if a piece of equipment requires manual intervention, you should set ``assistance_state`` to ``ASSISTANCE_STATE_NEEDED``. This will change the color and animation of the asset to show that it needs attention.

.. code-block:: python

    from artificial.api.alab.asset.asset_state_pb2 import AssetState

    @action()
    async def set_needs_assistance(self, actx: ActionExecutionContext, asset_id: str) -> t.List[str]:
        self.artificial_api.asset_api_v1.update(
            actx=actx, updates=[Asset.Update(id=asset_id, assistance_state=AssetState.ASSISTANCE_STATE_NEEDED)]
        )

Valid states are:

``ASSISTANCE_STATE_UNKNOWN`` (Default color, no animation)

``ASSISTANCE_STATE_NOT_IN_PROGRESS`` (Default color, no animation)

``ASSISTANCE_STATE_IN_PROGRESS`` (Blue, animated)

``ASSISTANCE_STATE_NEEDED`` (Yellow, no animation)



State Precedence
-----------------

States are applied in the following order of precedence with the highest precedence at the top:

``ASSET_OPS_STATE_VALUE_ERROR``

``ASSET_OPS_STATE_VALUE_CANCELING``

``ASSET_OPS_STATE_VALUE_CANCELED``

``ASSISTANCE_STATE_IN_PROGRESS``

``ASSISTANCE_STATE_NEEDED``

``ASSET_OPS_STATE_VALUE_OFFLINE``

``ASSET_OPS_STATE_VALUE_READY``

``ASSET_OPS_STATE_VALUE_RUNNING``

``ASSET_OPS_STATE_VALUE_RESUMING``

``ASSET_OPS_STATE_VALUE_PAUSING``

``ASSET_OPS_STATE_VALUE_PAUSED``

``ASSET_OPS_STATE_VALUE_GETTING_READY``

``ASSET_OPS_STATE_VALUE_UNKNOWN``

``ASSISTANCE_STATE_UNKNOWN``

``ASSISTANCE_STATE_NOT_IN_PROGRESS``