IotCoreClient (iotcore 1.0.0 API)

com.google.android.things.iotcore

Class IotCoreClient


  • public class IotCoreClient
extends Object
    IotCoreClient manages interactions with Google Cloud IoT Core for a single device.

    This class provides mechanisms for using Cloud IoT Core's main features. Namely

    • Publishing device telemetry
    • Publishing device state
    • Receiving configuration changes

    Create a new IotCoreClient using the IotCoreClient.Builder, and call connect() to initialize the client connection. When you no longer need to send and receive data, call disconnect() to close the connection and free up resources.

    Track the current connection using isConnected() or register a ConnectionCallback to listen for changes in the client's conn, and publish data to Cloud

    Publish data to Cloud IoT Core using publishTelemetry(TelemetryEvent) and publishDeviceState(byte[]). These methods can be used regardless of the client's connection state. If the client is connected, messages are published immediately. Otherwise, if the client is disconnected, messages are stored in memory and sent when the connection is reestablished.

    Register an OnConfigurationListener with the client to receive device configuration changes from Cloud IoT Core. 

         IotCoreClient iotCoreClient = new IotCoreClient.Builder()
             .setConnectionParams(connectionParams)
             .setKeyPair(keyPair);
             .setOnConfigurationListener(onConfigurationListener)
             .setConnectionCallback(connectionCallback)
             .build();
     iotCoreClient.connect();
     iotCoreClient.publishDeviceState("Hello world!".getBytes());

    While disconnected, the client queues all messages for delivery when the connection is restored. To customize the behavior of the offline message queue, call IotCoreClient.Builder.setTelemetryQueue(Queue) with a queue implementation suited to your application. If no queue implementation is provided, the default queue implementation is a queue that stores up to 1000 telemetry events and drops events from the head of the queue when messages are inserted beyond the maximum capacity.

    • Method Detail

      • connect

        public void connect()
        Connect to Cloud IoT Core and perform any other required set up.

        If the client registered a ConnectionCallback, ConnectionCallback.onConnected() will be called when the connection with Cloud IoT Core is established. If the IotCoreClient ever disconnects from Cloud IoT Core after this method is called, it will automatically reestablish the connection unless disconnect() is called.

        This method is non-blocking.

      • isConnected

        public boolean isConnected()
        Returns true if connected to Cloud IoT Core, and returns false otherwise.
        Returns:
        whether the client is connection to Cloud IoT Core

      • disconnect

        public void disconnect()
        Disconnect the client from Cloud IoT Core.

        This method is non-blocking.

      • publishTelemetry

        public boolean publishTelemetry(@NonNull
                                TelemetryEvent event)
        Add a telemetry event to this client's telemetry queue, if it is possible to do so without violating the telemetry queue's capacity restrictions, and publish the event to Cloud IoT Core as soon as possible.

        This method is non-blocking.

        Parameters:
        event - the telemetry event to publish
        Returns:
        Returns true if the event was queued to send, or return false if the event could not be queued

      • publishDeviceState

        public void publishDeviceState(byte[] state)
        Publishes state data to Cloud IoT Core.

        If the connection to Cloud IoT Core is lost and messages cannot be published to Cloud IoT Core, device state is published to Cloud IoT Core before any unpublished telemetry events when the connection is reestablished.

        If there are multiple attempts to publish device state while disconnected from Cloud IoT Core, only the newest device state will be published when the connection is reestablished.

        This method is non-blocking, and state is published using "at least once" semantics.

        Cloud IoT Core limits the number of device state updates per device to 1 per second. If clients of this library attempt to publish device state faster than that, some device state data may be lost when Cloud IoT Core resets the connection. The Cloud IoT Core documentation has more information about quotas and usage restrictions.

        Parameters:
        state - the device state data to publish