Utility
=======



The RPCs listed in this section are not directly tied to any other part of PhoneIoT, but are helpers with using them.



RPCS
----

.. function:: PhoneIoT.getColor(red: BoundedInteger<0, 255>, green: BoundedInteger<0, 255>, blue: BoundedInteger<0, 255>, alpha: BoundedInteger<0, 255>?)

    Many of the :doc:`Display` RPCs take one or more optional parameters for controlling display color, which is specified as an integer.
    This RPC is a convenience function for constructing a color code from ``red``, ``green``, ``blue``, and ``alpha`` values (each is ``0-255``).
    
    The ``alpha`` value controls transparency, with ``0`` being invisible and ``255`` being opaque.
    If not specified, ``alpha`` will default to ``255``.

    **Arguments:**

    - ``red: BoundedInteger<0, 255>`` (`BoundedInteger </docs/fundamentals/rpc-arg-types.html#BoundedInteger>`__) - red level (0-255)
    - ``green: BoundedInteger<0, 255>`` (`BoundedInteger </docs/fundamentals/rpc-arg-types.html#BoundedInteger>`__) - green level (0-255)
    - ``blue: BoundedInteger<0, 255>`` (`BoundedInteger </docs/fundamentals/rpc-arg-types.html#BoundedInteger>`__) - blue level (0-255)
    - ``alpha: BoundedInteger<0, 255>?`` (`BoundedInteger </docs/fundamentals/rpc-arg-types.html#BoundedInteger>`__) - alpha level (0-255)

    **Returns:** ``Color`` (`Color </docs/fundamentals/rpc-arg-types.html#Color>`__) - Constructed color code (an integer)


.. function:: PhoneIoT.getSensors()

    This RPC returns a list containing the name of every sensor supported by PhoneIoT.
    Note that your specific device might not support all of these sensors, depending on the model.
    
    See :doc:`Sensors` for more information.

    **Returns:** ``List`` (`List </docs/fundamentals/rpc-arg-types.html#List>`__) - A list of sensor names


.. function:: PhoneIoT.vibrate(device: Device, durations: AnyOf<List<VibrationDuration>, VibrationDuration>, strength: VibrationStrength?)

    Causes the phone to vibrate with a specified duration (in seconds) and strength.
    ``durations`` can either be a single number representing a continuous vibration for that amount of time (in seconds), or it can be a list of durations.
    For instance, ``[1, 0.5, 2]`` would mean: vibrate for 1 second, stop for 0.5 seconds, then vibrate for 2 seconds.
    
    Some older devices lack support for customizable vibration patterns/durations,
    in which case PhoneIoT may have to resort to an approximation of the desired pattern using longer vibrations.

    **Arguments:**

    - ``device: Device`` (`Device </docs/fundamentals/rpc-arg-types.html#Device>`__) - id of the device
    - ``durations: AnyOf<List<VibrationDuration>, VibrationDuration>`` (`AnyOf </docs/fundamentals/rpc-arg-types.html#AnyOf>`__ | `List </docs/fundamentals/rpc-arg-types.html#List>`__ | `VibrationDuration </docs/fundamentals/rpc-arg-types.html#VibrationDuration>`__) - the duration of a vibration or a pattern of on/off times
    - ``strength: VibrationStrength?`` (`VibrationStrength </docs/fundamentals/rpc-arg-types.html#VibrationStrength>`__) - the strength of vibration (default 100)