@scratch/scratch-vm 11.0.0-beta.1

package/src/io/ble.js

@@ -0,0 +1,256 @@
+const JSONRPC = require('../util/jsonrpc');
+
+class BLE extends JSONRPC {
+
+    /**
+     * A BLE peripheral socket object.  It handles connecting, over web sockets, to
+     * BLE peripherals, and reading and writing data to them.
+     * @param {Runtime} runtime - the Runtime for sending/receiving GUI update events.
+     * @param {string} extensionId - the id of the extension using this socket.
+     * @param {object} peripheralOptions - the list of options for peripheral discovery.
+     * @param {object} connectCallback - a callback for connection.
+     * @param {object} resetCallback - a callback for resetting extension state.
+     */
+    constructor (runtime, extensionId, peripheralOptions, connectCallback, resetCallback = null) {
+        super();
+
+        this._socket = runtime.getScratchLinkSocket('BLE');
+        this._socket.setOnOpen(this.requestPeripheral.bind(this));
+        this._socket.setOnClose(this.handleDisconnectError.bind(this));
+        this._socket.setOnError(this._handleRequestError.bind(this));
+        this._socket.setHandleMessage(this._handleMessage.bind(this));
+
+        this._sendMessage = this._socket.sendMessage.bind(this._socket);
+
+        this._availablePeripherals = {};
+        this._connectCallback = connectCallback;
+        this._connected = false;
+        this._characteristicDidChangeCallback = null;
+        this._resetCallback = resetCallback;
+        this._discoverTimeoutID = null;
+        this._extensionId = extensionId;
+        this._peripheralOptions = peripheralOptions;
+        this._runtime = runtime;
+
+        this._socket.open();
+    }
+
+    /**
+     * Request connection to the peripheral.
+     * If the web socket is not yet open, request when the socket promise resolves.
+     */
+    requestPeripheral () {
+        this._availablePeripherals = {};
+        if (this._discoverTimeoutID) {
+            window.clearTimeout(this._discoverTimeoutID);
+        }
+        this._discoverTimeoutID = window.setTimeout(this._handleDiscoverTimeout.bind(this), 15000);
+        this.sendRemoteRequest('discover', this._peripheralOptions)
+            .catch(e => {
+                this._handleRequestError(e);
+            });
+    }
+
+    /**
+     * Try connecting to the input peripheral id, and then call the connect
+     * callback if connection is successful.
+     * @param {number} id - the id of the peripheral to connect to
+     */
+    connectPeripheral (id) {
+        this.sendRemoteRequest('connect', {peripheralId: id})
+            .then(() => {
+                this._connected = true;
+                this._runtime.emit(this._runtime.constructor.PERIPHERAL_CONNECTED);
+                this._connectCallback();
+            })
+            .catch(e => {
+                this._handleRequestError(e);
+            });
+    }
+
+    /**
+     * Close the websocket.
+     */
+    disconnect () {
+        if (this._connected) {
+            this._connected = false;
+        }
+
+        if (this._socket.isOpen()) {
+            this._socket.close();
+        }
+
+        if (this._discoverTimeoutID) {
+            window.clearTimeout(this._discoverTimeoutID);
+        }
+
+        // Sets connection status icon to orange
+        this._runtime.emit(this._runtime.constructor.PERIPHERAL_DISCONNECTED);
+    }
+
+    /**
+     * @return {bool} whether the peripheral is connected.
+     */
+    isConnected () {
+        return this._connected;
+    }
+
+    /**
+     * Start receiving notifications from the specified ble service.
+     * @param {number} serviceId - the ble service to read.
+     * @param {number} characteristicId - the ble characteristic to get notifications from.
+     * @param {object} onCharacteristicChanged - callback for characteristic change notifications.
+     * @return {Promise} - a promise from the remote startNotifications request.
+     */
+    startNotifications (serviceId, characteristicId, onCharacteristicChanged = null) {
+        const params = {
+            serviceId,
+            characteristicId
+        };
+        this._characteristicDidChangeCallback = onCharacteristicChanged;
+        return this.sendRemoteRequest('startNotifications', params)
+            .catch(e => {
+                this.handleDisconnectError(e);
+            });
+    }
+
+    /**
+     * Read from the specified ble service.
+     * @param {number} serviceId - the ble service to read.
+     * @param {number} characteristicId - the ble characteristic to read.
+     * @param {boolean} optStartNotifications - whether to start receiving characteristic change notifications.
+     * @param {object} onCharacteristicChanged - callback for characteristic change notifications.
+     * @return {Promise} - a promise from the remote read request.
+     */
+    read (serviceId, characteristicId, optStartNotifications = false, onCharacteristicChanged = null) {
+        const params = {
+            serviceId,
+            characteristicId
+        };
+        if (optStartNotifications) {
+            params.startNotifications = true;
+        }
+        if (onCharacteristicChanged) {
+            this._characteristicDidChangeCallback = onCharacteristicChanged;
+        }
+        return this.sendRemoteRequest('read', params)
+            .catch(e => {
+                this.handleDisconnectError(e);
+            });
+    }
+
+    /**
+     * Write data to the specified ble service.
+     * @param {number} serviceId - the ble service to write.
+     * @param {number} characteristicId - the ble characteristic to write.
+     * @param {string} message - the message to send.
+     * @param {string} encoding - the message encoding type.
+     * @param {boolean} withResponse - if true, resolve after peripheral's response.
+     * @return {Promise} - a promise from the remote send request.
+     */
+    write (serviceId, characteristicId, message, encoding = null, withResponse = null) {
+        const params = {serviceId, characteristicId, message};
+        if (encoding) {
+            params.encoding = encoding;
+        }
+        if (withResponse !== null) {
+            params.withResponse = withResponse;
+        }
+        return this.sendRemoteRequest('write', params)
+            .catch(e => {
+                this.handleDisconnectError(e);
+            });
+    }
+
+    /**
+     * Handle a received call from the socket.
+     * @param {string} method - a received method label.
+     * @param {object} params - a received list of parameters.
+     * @return {object} - optional return value.
+     */
+    didReceiveCall (method, params) {
+        switch (method) {
+        case 'didDiscoverPeripheral':
+            this._availablePeripherals[params.peripheralId] = params;
+            this._runtime.emit(
+                this._runtime.constructor.PERIPHERAL_LIST_UPDATE,
+                this._availablePeripherals
+            );
+            if (this._discoverTimeoutID) {
+                window.clearTimeout(this._discoverTimeoutID);
+            }
+            break;
+        case 'userDidPickPeripheral':
+            this._availablePeripherals[params.peripheralId] = params;
+            this._runtime.emit(
+                this._runtime.constructor.USER_PICKED_PERIPHERAL,
+                this._availablePeripherals
+            );
+            if (this._discoverTimeoutID) {
+                window.clearTimeout(this._discoverTimeoutID);
+            }
+            break;
+        case 'userDidNotPickPeripheral':
+            this._runtime.emit(
+                this._runtime.constructor.PERIPHERAL_SCAN_TIMEOUT
+            );
+            if (this._discoverTimeoutID) {
+                window.clearTimeout(this._discoverTimeoutID);
+            }
+            break;
+        case 'characteristicDidChange':
+            if (this._characteristicDidChangeCallback) {
+                this._characteristicDidChangeCallback(params.message);
+            }
+            break;
+        case 'ping':
+            return 42;
+        }
+    }
+
+    /**
+     * Handle an error resulting from losing connection to a peripheral.
+     *
+     * This could be due to:
+     * - battery depletion
+     * - going out of bluetooth range
+     * - being powered down
+     *
+     * Disconnect the socket, and if the extension using this socket has a
+     * reset callback, call it. Finally, emit an error to the runtime.
+     */
+    handleDisconnectError (/* e */) {
+        // log.error(`BLE error: ${JSON.stringify(e)}`);
+
+        if (!this._connected) return;
+
+        this.disconnect();
+
+        if (this._resetCallback) {
+            this._resetCallback();
+        }
+
+        this._runtime.emit(this._runtime.constructor.PERIPHERAL_CONNECTION_LOST_ERROR, {
+            message: `Scratch lost connection to`,
+            extensionId: this._extensionId
+        });
+    }
+
+    _handleRequestError (/* e */) {
+        // log.error(`BLE error: ${JSON.stringify(e)}`);
+
+        this._runtime.emit(this._runtime.constructor.PERIPHERAL_REQUEST_ERROR, {
+            message: `Scratch lost connection to`,
+            extensionId: this._extensionId
+        });
+    }
+
+    _handleDiscoverTimeout () {
+        if (this._discoverTimeoutID) {
+            window.clearTimeout(this._discoverTimeoutID);
+        }
+        this._runtime.emit(this._runtime.constructor.PERIPHERAL_SCAN_TIMEOUT);
+    }
+}
+
+module.exports = BLE;

package/src/io/bt.js

@@ -0,0 +1,202 @@
+const JSONRPC = require('../util/jsonrpc');
+
+class BT extends JSONRPC {
+
+    /**
+     * A BT peripheral socket object.  It handles connecting, over web sockets, to
+     * BT peripherals, and reading and writing data to them.
+     * @param {Runtime} runtime - the Runtime for sending/receiving GUI update events.
+     * @param {string} extensionId - the id of the extension using this socket.
+     * @param {object} peripheralOptions - the list of options for peripheral discovery.
+     * @param {object} connectCallback - a callback for connection.
+     * @param {object} resetCallback - a callback for resetting extension state.
+     * @param {object} messageCallback - a callback for message sending.
+     */
+    constructor (runtime, extensionId, peripheralOptions, connectCallback, resetCallback = null, messageCallback) {
+        super();
+
+        this._socket = runtime.getScratchLinkSocket('BT');
+        this._socket.setOnOpen(this.requestPeripheral.bind(this));
+        this._socket.setOnError(this._handleRequestError.bind(this));
+        this._socket.setOnClose(this.handleDisconnectError.bind(this));
+        this._socket.setHandleMessage(this._handleMessage.bind(this));
+
+        this._sendMessage = this._socket.sendMessage.bind(this._socket);
+
+        this._availablePeripherals = {};
+        this._connectCallback = connectCallback;
+        this._connected = false;
+        this._characteristicDidChangeCallback = null;
+        this._resetCallback = resetCallback;
+        this._discoverTimeoutID = null;
+        this._extensionId = extensionId;
+        this._peripheralOptions = peripheralOptions;
+        this._messageCallback = messageCallback;
+        this._runtime = runtime;
+
+        this._socket.open();
+    }
+
+    /**
+     * Request connection to the peripheral.
+     * If the web socket is not yet open, request when the socket promise resolves.
+     */
+    requestPeripheral () {
+        this._availablePeripherals = {};
+        if (this._discoverTimeoutID) {
+            window.clearTimeout(this._discoverTimeoutID);
+        }
+        this._discoverTimeoutID = window.setTimeout(this._handleDiscoverTimeout.bind(this), 15000);
+        this.sendRemoteRequest('discover', this._peripheralOptions)
+            .catch(
+                e => this._handleRequestError(e)
+            );
+    }
+
+    /**
+     * Try connecting to the input peripheral id, and then call the connect
+     * callback if connection is successful.
+     * @param {number} id - the id of the peripheral to connect to
+     * @param {string} pin - an optional pin for pairing
+     */
+    connectPeripheral (id, pin = null) {
+        const params = {peripheralId: id};
+        if (pin) {
+            params.pin = pin;
+        }
+        this.sendRemoteRequest('connect', params)
+            .then(() => {
+                this._connected = true;
+                this._runtime.emit(this._runtime.constructor.PERIPHERAL_CONNECTED);
+                this._connectCallback();
+            })
+            .catch(e => {
+                this._handleRequestError(e);
+            });
+    }
+
+    /**
+     * Close the websocket.
+     */
+    disconnect () {
+        if (this._connected) {
+            this._connected = false;
+        }
+
+        if (this._socket.isOpen()) {
+            this._socket.close();
+        }
+
+        if (this._discoverTimeoutID) {
+            window.clearTimeout(this._discoverTimeoutID);
+        }
+
+        // Sets connection status icon to orange
+        this._runtime.emit(this._runtime.constructor.PERIPHERAL_DISCONNECTED);
+    }
+
+    /**
+     * @return {bool} whether the peripheral is connected.
+     */
+    isConnected () {
+        return this._connected;
+    }
+
+    sendMessage (options) {
+        return this.sendRemoteRequest('send', options)
+            .catch(e => {
+                this.handleDisconnectError(e);
+            });
+    }
+
+    /**
+     * Handle a received call from the socket.
+     * @param {string} method - a received method label.
+     * @param {object} params - a received list of parameters.
+     * @return {object} - optional return value.
+     */
+    didReceiveCall (method, params) {
+        // TODO: Add peripheral 'undiscover' handling
+        switch (method) {
+        case 'didDiscoverPeripheral':
+            this._availablePeripherals[params.peripheralId] = params;
+            this._runtime.emit(
+                this._runtime.constructor.PERIPHERAL_LIST_UPDATE,
+                this._availablePeripherals
+            );
+            if (this._discoverTimeoutID) {
+                window.clearTimeout(this._discoverTimeoutID);
+            }
+            break;
+        case 'userDidPickPeripheral':
+            this._availablePeripherals[params.peripheralId] = params;
+            this._runtime.emit(
+                this._runtime.constructor.USER_PICKED_PERIPHERAL,
+                this._availablePeripherals
+            );
+            if (this._discoverTimeoutID) {
+                window.clearTimeout(this._discoverTimeoutID);
+            }
+            break;
+        case 'userDidNotPickPeripheral':
+            this._runtime.emit(
+                this._runtime.constructor.PERIPHERAL_SCAN_TIMEOUT
+            );
+            if (this._discoverTimeoutID) {
+                window.clearTimeout(this._discoverTimeoutID);
+            }
+            break;
+        case 'didReceiveMessage':
+            this._messageCallback(params); // TODO: refine?
+            break;
+        default:
+            return 'nah';
+        }
+    }
+
+    /**
+     * Handle an error resulting from losing connection to a peripheral.
+     *
+     * This could be due to:
+     * - battery depletion
+     * - going out of bluetooth range
+     * - being powered down
+     *
+     * Disconnect the socket, and if the extension using this socket has a
+     * reset callback, call it. Finally, emit an error to the runtime.
+     */
+    handleDisconnectError (/* e */) {
+        // log.error(`BT error: ${JSON.stringify(e)}`);
+
+        if (!this._connected) return;
+
+        this.disconnect();
+
+        if (this._resetCallback) {
+            this._resetCallback();
+        }
+
+        this._runtime.emit(this._runtime.constructor.PERIPHERAL_CONNECTION_LOST_ERROR, {
+            message: `Scratch lost connection to`,
+            extensionId: this._extensionId
+        });
+    }
+
+    _handleRequestError (/* e */) {
+        // log.error(`BT error: ${JSON.stringify(e)}`);
+
+        this._runtime.emit(this._runtime.constructor.PERIPHERAL_REQUEST_ERROR, {
+            message: `Scratch lost connection to`,
+            extensionId: this._extensionId
+        });
+    }
+
+    _handleDiscoverTimeout () {
+        if (this._discoverTimeoutID) {
+            window.clearTimeout(this._discoverTimeoutID);
+        }
+        this._runtime.emit(this._runtime.constructor.PERIPHERAL_SCAN_TIMEOUT);
+    }
+}
+
+module.exports = BT;

package/src/io/clock.js

@@ -0,0 +1,39 @@
+const Timer = require('../util/timer');
+
+class Clock {
+    constructor (runtime) {
+        this._projectTimer = new Timer({now: () => runtime.currentMSecs});
+        this._projectTimer.start();
+        this._pausedTime = null;
+        this._paused = false;
+        /**
+         * Reference to the owning Runtime.
+         * @type{!Runtime}
+         */
+        this.runtime = runtime;
+    }
+
+    projectTimer () {
+        if (this._paused) {
+            return this._pausedTime / 1000;
+        }
+        return this._projectTimer.timeElapsed() / 1000;
+    }
+
+    pause () {
+        this._paused = true;
+        this._pausedTime = this._projectTimer.timeElapsed();
+    }
+
+    resume () {
+        this._paused = false;
+        const dt = this._projectTimer.timeElapsed() - this._pausedTime;
+        this._projectTimer.startTime += dt;
+    }
+
+    resetProjectTimer () {
+        this._projectTimer.start();
+    }
+}
+
+module.exports = Clock;

package/src/io/cloud.js

@@ -0,0 +1,169 @@
+const Variable = require('../engine/variable');
+const log = require('../util/log');
+
+class Cloud {
+    /**
+     * @typedef updateVariable
+     * @param {string} name The name of the cloud variable to update on the server
+     * @param {(string | number)} value The value to update the cloud variable with.
+     */
+
+    /**
+     * A cloud data provider, responsible for managing the connection to the
+     * cloud data server and for posting data about cloud data activity to
+     * this IO device.
+     * @typedef {object} CloudProvider
+     * @property {updateVariable} updateVariable A function which sends a cloud variable
+     * update to the cloud data server.
+     * @property {Function} requestCloseConnection A function which closes
+     * the connection to the cloud data server.
+     */
+
+    /**
+     * Part of a cloud io data post indicating a cloud variable update.
+     * @typedef {object} VarUpdateData
+     * @property {string} name The name of the variable to update
+     * @property {(number | string)} value The scalar value to update the variable with
+     */
+
+    /**
+     * A cloud io data post message.
+     * @typedef {object} CloudIOData
+     * @property {VarUpdateData} varUpdate A {@link VarUpdateData} message indicating
+     * a cloud variable update
+     */
+
+    /**
+     * Cloud IO Device responsible for sending and receiving messages from
+     * cloud provider (mananging the cloud server connection) and interacting
+     * with cloud variables in the current project.
+     * @param {Runtime} runtime The runtime context for this cloud io device.
+     */
+    constructor (runtime) {
+        /**
+         * Reference to the cloud data provider, responsible for mananging
+         * the web socket connection to the cloud data server.
+         * @type {?CloudProvider}
+         */
+        this.provider = null;
+
+        /**
+         * Reference to the runtime that owns this cloud io device.
+         * @type {!Runtime}
+         */
+        this.runtime = runtime;
+
+        /**
+         * Reference to the stage target which owns the cloud variables
+         * in the project.
+         * @type {?Target}
+         */
+        this.stage = null;
+    }
+
+    /**
+     * Set a reference to the cloud data provider.
+     * @param {CloudProvider} provider The cloud data provider
+     */
+    setProvider (provider) {
+        this.provider = provider;
+    }
+
+    /**
+     * Set a reference to the stage target which owns the
+     * cloud variables in the project.
+     * @param {Target} stage The stage target
+     */
+    setStage (stage) {
+        this.stage = stage;
+    }
+
+    /**
+     * Handle incoming data to this io device.
+     * @param {CloudIOData} data The {@link CloudIOData} object to process
+     */
+    postData (data) {
+        if (data.varUpdate) {
+            this.updateCloudVariable(data.varUpdate);
+        }
+    }
+
+    requestCreateVariable (variable) {
+        if (this.runtime.canAddCloudVariable()) {
+            if (this.provider) {
+                this.provider.createVariable(variable.name, variable.value);
+                // We'll set the cloud flag and update the
+                // cloud variable limit when we actually
+                // get a confirmation from the cloud data server
+            }
+        } // TODO else track creation for later
+    }
+
+    /**
+     * Request the cloud data provider to update the given variable with
+     * the given value. Does nothing if this io device does not have a provider set.
+     * @param {string} name The name of the variable to update
+     * @param {string | number} value The value to update the variable with
+     */
+    requestUpdateVariable (name, value) {
+        if (this.provider) {
+            this.provider.updateVariable(name, value);
+        }
+    }
+
+    /**
+     * Request the cloud data provider to rename the variable with the given name
+     * to the given new name. Does nothing if this io device does not have a provider set.
+     * @param {string} oldName The name of the variable to rename
+     * @param {string | number} newName The new name for the variable
+     */
+    requestRenameVariable (oldName, newName) {
+        if (this.provider) {
+            this.provider.renameVariable(oldName, newName);
+        }
+    }
+
+    /**
+     * Request the cloud data provider to delete the variable with the given name
+     * Does nothing if this io device does not have a provider set.
+     * @param {string} name The name of the variable to delete
+     */
+    requestDeleteVariable (name) {
+        if (this.provider) {
+            this.provider.deleteVariable(name);
+        }
+    }
+
+    /**
+     * Update a cloud variable in the runtime based on the message received
+     * from the cloud provider.
+     * @param {VarData} varUpdate A {@link VarData} object describing
+     * a cloud variable update received from the cloud data provider.
+     */
+    updateCloudVariable (varUpdate) {
+        const varName = varUpdate.name;
+
+        const variable = this.stage.lookupVariableByNameAndType(varName, Variable.SCALAR_TYPE);
+        if (!variable || !variable.isCloud) {
+            log.warn(`Received an update for a cloud variable that does not exist: ${varName}`);
+            return;
+        }
+
+        variable.value = varUpdate.value;
+    }
+
+    /**
+     * Request the cloud data provider to close the web socket connection and
+     * clear this io device of references to the cloud data provider and the
+     * stage.
+     */
+    clear () {
+        if (!this.provider) return;
+
+        this.provider.requestCloseConnection();
+        this.provider = null;
+        this.stage = null;
+    }
+}
+
+module.exports = Cloud;