PhoneIoT
========
PhoneIoT is a service in `NetsBlox `__ that's meant to teach Internet of Things (IoT) topics as early as K-12 education.
It allows you to programmatically access your smartphone's sensors and display.
This includes accessing hardware sensors such as the accelerometer, gyroscope, microphone, camera, and many others depending on the device.
PhoneIoT also allows you to control a customizable interactive display, enabling you to use your device as a custom remote control, or even create and run distributed (multiplayer) applications.
The limits are up to your imagination!
To get started using PhoneIoT, download the PhoneIoT app on your mobile device, available for `Android `__ and iOS, and then go to the `NetsBlox editor `__.
In the top left of the editor, you should see a grid of several colored tabs.
Under the ``Network`` tab, grab a ``call`` block and place it in the center script area.
Click the first dropdown on the ``call`` block and select the ``PhoneIoT`` service.
The second dropdown selects the specific *Remote Procedure Call* (RPC) to execute - see the table of contents for information about the various RPCs.
Inside the PhoneIoT app on your mobile device, click the button at the top left to open the menu, and then click ``connect``.
If you successfully connected, you should get a small popup message at the bottom of the screen.
`If you don't see this message, make sure you have either Wi-Fi or mobile data turned on and try again.`
Near the top of the menu, you should see an ID and password, which will be needed to connect to the device from NetsBlox.
Back in NetsBlox, select the ``setCredentials`` RPC and give it your ID and password.
For convenience, you might want to save the ID in a variable (e.g. ``device``), as it will be referenced many times.
If you click the ``call`` block to run it, you should get an ``OK`` result, meaning you successfully connected.
`If you don't see this, make sure you entered the ID and password correctly.`
You're now ready to start using the other RPCs in PhoneIoT to communicate with the device!
.. toctree::
:maxdepth: 2
:titlesonly:
:caption: RPC Categories
Display.rst
Sensors.rst
Utility.rst
RPCS
----
.. function:: PhoneIoT.authenticate(device: Device)
This RPC simply checks that the connection to the device is still good.
In particular, you can use this to check if the password is still valid.
**Arguments:**
- ``device: Device`` (`Device `__) - id of the device
.. function:: PhoneIoT.listenToGUI(device: Device)
This RPC requests that you receive any events from the *Graphical User Interface* (GUI) on the phone's display.
This is needed to receive any type of GUI event, including button clicks, joystick movements, and textbox update events.
You only need to call this RPC once, which you can do at the start of your program (but after calling :func:`PhoneIoT.setCredentials`).
Adding a widget/control to the device will automatically register that project to listen for GUI updates,
so it is not typically required to call this RPC directly.
However, this is still available in the case that a project needs to listen to events without actually creating any widgets itself
(e.g., if another project sets up the GUI and this project only needs to listen to events).
See the :doc:`Display` section for more information.
**Arguments:**
- ``device: Device`` (`Device `__) - id of the device
.. function:: PhoneIoT.listenToSensors(device: Device, sensors: Object?)
This RPC requests that you receive periodic sensor update events from the device.
The ``sensors`` input is a list of pairs (lists of length 2), where each pair is a sensor name and an update period in milliseconds.
You can have different update periods for different sensors.
You will receive a message of the same name as the sensor at most once per whatever update period you specified.
Any call to this RPC will invalidate all previous calls - thus, calling it with an empty list will stop all updates.
Alternatively, the dedicated :func:`PhoneIoT.stopSensors` RPC will likewise stop all updates.
This method of accessing sensor data is often easier, as it doesn't require loops or error-checking code.
If a networking error occurs, you simply miss that single message.
The :func:`PhoneIoT.getSensors` RPC can be used to get a list of the valid sensor names.
See the :doc:`Sensors` section for more information, esp. the required fields for each message type.
**Arguments:**
- ``device: Device`` (`Device `__) - id of the device
- ``sensors: Object?`` (`Object `__) - structured data representing the minimum time in milliseconds between updates for each sensor type to listen for
- ``gravity: SensorPeriod?`` (`SensorPeriod `__) - ``gravity`` period
- ``gyroscope: SensorPeriod?`` (`SensorPeriod `__) - ``gyroscope`` period
- ``orientation: SensorPeriod?`` (`SensorPeriod `__) - ``orientation`` period
- ``accelerometer: SensorPeriod?`` (`SensorPeriod `__) - ``accelerometer`` period
- ``magneticField: SensorPeriod?`` (`SensorPeriod `__) - ``magneticField`` period
- ``linearAcceleration: SensorPeriod?`` (`SensorPeriod `__) - ``linearAcceleration`` period
- ``lightLevel: SensorPeriod?`` (`SensorPeriod `__) - ``lightLevel`` period
- ``microphoneLevel: SensorPeriod?`` (`SensorPeriod `__) - ``microphoneLevel`` period
- ``proximity: SensorPeriod?`` (`SensorPeriod `__) - ``proximity`` period
- ``stepCount: SensorPeriod?`` (`SensorPeriod `__) - ``stepCount`` period
- ``location: SensorPeriod?`` (`SensorPeriod `__) - ``location`` period
- ``pressure: SensorPeriod?`` (`SensorPeriod `__) - ``pressure`` period
- ``temperature: SensorPeriod?`` (`SensorPeriod `__) - ``temperature`` period
- ``humidity: SensorPeriod?`` (`SensorPeriod `__) - ``humidity`` period
.. function:: PhoneIoT.setCredentials(device: Device, password: String)
This is the first RPC you should *always* call when working with PhoneIoT.
It sets the login credentials (password) to use for all future interactions with the device.
**Arguments:**
- ``device: Device`` (`Device `__) - id of the device
- ``password: String`` (`String `__) - the password to use for accessing the device
.. function:: PhoneIoT.stopSensors(device: Device)
Stops outgoing sensor updates that were previously requested by :func:`PhoneIoT.listenToSensors`.
This is equivalent to calling :func:`PhoneIoT.listenToSensors` with an empty sensors list,
but is provided as a separate RPC for convenience and discoverability.
**Arguments:**
- ``device: Device`` (`Device `__) - id of the device