Class Pixel

Represents a Pixels die. Most of its methods require the instance to be connected to the Pixel device. Call the () method to initiate a connection.

Call addEventListener to get notified for rolls, connection and disconnection events and more.

Call addPropertyListener to get notified on property changes.

Hierarchy (view full)

Constructors

constructor

Properties

_createRollEvent _deserializeImADie _dispose _disposeFunc _evEmitter _info _internalSetup _log _logArray _logData _logFunc _logMessages _msgEvEmitter _onValueChanged _session _status _tagLogString _updateBattery _updateColorway _updateDieType _updateFirmwareDate _updateLedCount _updateName _updateRoll _updateRssi _updateStatus _uploadBulkData _versions _warn waitForMessage MutablePropsList

Accessors

batteryLevel colorway currentFace currentFaceIndex dieFaceCount dieType firmwareDate isCharging isReady ledCount logMessages logMessagesSerializedData logger name pixelId rollState rssi status systemId

Methods

addEventListener addMessageListener addPropertyListener blink connect disconnect emitPropertyEvent playInstantAnimation playTestAnimation queryRssi removeEventListener removeMessageListener removePropertyListener rename reportRssi sendAndWaitForResponse sendAndWaitForTypedResponse sendMessage startCalibration stopAllAnimations transferDataSet transferInstantAnimations turnOff updateInfo uploadBulkDataWithAck

Constructors

constructor

  • new Pixel(session, info?): Pixel

  • Instantiates a Pixel.

    Parameters

    • session: PixelSession

      The session used to communicate with the Pixel.

    • Optional info: Partial<Pick<PixelInfo, "pixelId" | "ledCount" | "colorway" | "dieType" | "firmwareDate">>

    Returns Pixel

Properties

Private _createRollEvent

_createRollEvent: any

Private _deserializeImADie

_deserializeImADie: any

Private _dispose

_dispose: any

/!\ Internal, don't call this function ;)

Private _disposeFunc

_disposeFunc: any

Private Readonly _evEmitter

_evEmitter: any

Private Readonly _info

_info: any

Private _internalSetup

_internalSetup: any

Private _log

_log: any

Private _logArray

_logArray: any

Private _logData

_logData: any

Private _logFunc

_logFunc: any

Private _logMessages

_logMessages: any

Private Readonly _msgEvEmitter

_msgEvEmitter: any

Private _onValueChanged

_onValueChanged: any

Private Readonly _session

_session: any

Private _status

_status: any

Private _tagLogString

_tagLogString: any

Private _updateBattery

_updateBattery: any

Private _updateColorway

_updateColorway: any

Private _updateDieType

_updateDieType: any

Private _updateFirmwareDate

_updateFirmwareDate: any

Private _updateLedCount

_updateLedCount: any

Private _updateName

_updateName: any

Private _updateRoll

_updateRoll: any

Private _updateRssi

_updateRssi: any

Private _updateStatus

_updateStatus: any

Private _uploadBulkData

_uploadBulkData: any

Private Readonly _versions

_versions: any

Private _warn

_warn: any

Private waitForMessage

waitForMessage: any

Waits for a message from the Pixel.

Param: expectedMsgType

Type of the message to expect.

Param: timeoutMs

Timeout before aborting the wait.

Returns

A promise with the received message of the expected type.

Static MutablePropsList

MutablePropsList: readonly (keyof PixelInfo)[]

Accessors

batteryLevel

  • get batteryLevel(): number

  • Get the Pixel battery level (percentage).

    Returns number

    Remarks

    This value is automatically updated when the die is connected.

colorway

  • get colorway(): "custom" | "clear" | "unknown" | "onyxBlack" | "hematiteGrey" | "midnightGalaxy" | "auroraSky"

  • Gets the color of the Pixel.

    Returns "custom" | "clear" | "unknown" | "onyxBlack" | "hematiteGrey" | "midnightGalaxy" | "auroraSky"

currentFace

  • get currentFace(): number

  • Get the die face value that is currently facing up.

    Returns number

    Remarks

    Fudge die returns +1, 0 and -1. This value is automatically updated when the die is connected.

currentFaceIndex

  • get currentFaceIndex(): number

  • Get the 0-based index of the die face that is currently facing up.

    Returns number

    Remarks

    This value is automatically updated when the die is connected.

    See

    PixelInfo.currentFaceIndex for more details.

dieFaceCount

  • get dieFaceCount(): number

  • Gets the number of faces of the Pixel.

    Returns number

dieType

  • get dieType(): "unknown" | "d4" | "d6" | "d8" | "d10" | "d00" | "d12" | "d20" | "d6pipped" | "d6fudge"

  • Gets the die type of the Pixel.

    Returns "unknown" | "d4" | "d6" | "d8" | "d10" | "d00" | "d12" | "d20" | "d6pipped" | "d6fudge"

firmwareDate

  • get firmwareDate(): Date

  • Get the Pixel firmware build date.

    Returns Date

isCharging

  • get isCharging(): boolean

  • Gets whether the Pixel battery is charging or not. Returns 'true' if fully charged but still on charger.

    Returns boolean

    Remarks

    This value is automatically updated when the die is connected.

isReady

  • get isReady(): boolean

  • Shorthand property that indicates if the Pixel status is "ready".

    Returns boolean

ledCount

  • get ledCount(): number

  • Gets the number of LEDs for the Pixel, may be 0 until connected to device.

    Returns number

logMessages

  • get logMessages(): boolean

  • Toggle logging information about each send and received message.

    Returns boolean

  • set logMessages(enabled): void

  • Parameters

    • enabled: boolean

    Returns void

logMessagesSerializedData

  • get logMessagesSerializedData(): boolean

  • Toggle logging the serialized (binary) data for each send and received message.

    Returns boolean

  • set logMessagesSerializedData(enabled): void

  • Parameters

    • enabled: boolean

    Returns void

logger

  • get logger(): undefined | null | ((msg) => void)

  • Set logger to use by this instance.

    Returns undefined | null | ((msg) => void)

  • set logger(logger): void

  • Parameters

    • logger: undefined | null | ((msg) => void)

    Returns void

name

  • get name(): string

  • Get the Pixel name, may be empty until connected to device.

    Returns string

pixelId

  • get pixelId(): number

  • Gets the unique Pixel id of the device, may be 0 until connected.

    Returns number

rollState

  • get rollState(): "unknown" | "handling" | "rolling" | "crooked" | "onFace"

  • Get the Pixel roll state.

    Returns "unknown" | "handling" | "rolling" | "crooked" | "onFace"

    Remarks

    This value is automatically updated when the die is connected.

rssi

  • get rssi(): number

  • Gets the last RSSI value notified by the Pixel.

    Returns number

    Remarks

    Call () to automatically update the RSSI value.

status

  • get status(): PixelStatus

  • Get the Pixel last known connection status.

    Returns PixelStatus

systemId

  • get systemId(): string

  • Gets the unique id assigned by the system to the Pixel Bluetooth peripheral.

    Returns string

Methods

addEventListener

  • addEventListener<K>(type, listener): void

  • Registers a listener function that will be called when the specified event is raised. See PixelEventMap for the list of events and their associated data.

    Type Parameters

    Parameters

    Returns void

addMessageListener

  • addMessageListener(msgType, listener): void

  • Registers a listener function that will be called on receiving raw messages of a given type from the Pixel.

    Parameters

    • msgType: "blink" | "none" | "whoAreYou" | "iAmADie" | "rollState" | "telemetry" | "bulkSetup" | "bulkSetupAck" | "bulkData" | "bulkDataAck" | "transferAnimationSet" | "transferAnimationSetAck" | "transferAnimationSetFinished" | "transferSettings" | "transferSettingsAck" | "transferSettingsFinished" | "transferTestAnimationSet" | "transferTestAnimationSetAck" | "transferTestAnimationSetFinished" | "debugLog" | "playAnimation" | "playAnimationEvent" | "stopAnimation" | "remoteAction" | "requestRollState" | "requestAnimationSet" | "requestSettings" | "requestTelemetry" | "programDefaultAnimationSet" | "programDefaultAnimationSetFinished" | "blinkAck" | "requestDefaultAnimationSetColor" | "defaultAnimationSetColor" | "requestBatteryLevel" | "batteryLevel" | "requestRssi" | "rssi" | "calibrate" | "calibrateFace" | "notifyUser" | "notifyUserAck" | "testHardware" | "storeValue" | "storeValueAck" | "setTopLevelState" | "programDefaultParameters" | "programDefaultParametersFinished" | "setDesignAndColor" | "setDesignAndColorAck" | "setCurrentBehavior" | "setCurrentBehaviorAck" | "setName" | "setNameAck" | "powerOperation" | "exitValidation" | "transferInstantAnimationSet" | "transferInstantAnimationSetAck" | "transferInstantAnimationSetFinished" | "playInstantAnimation" | "stopAllAnimations" | "requestTemperature" | "temperature" | "setBatteryControllerMode" | "_unused" | "discharge" | "blinkId" | "blinkIdAck" | "transferTest" | "transferTestAck" | "transferTestFinished" | "clearSettings" | "clearSettingsAck" | "testBulkSend" | "testBulkReceive" | "setAllLEDsToColor" | "attractMode" | "printNormals" | "printA2DReadings" | "lightUpFace" | "setLEDToColor" | "debugAnimationController"

      The type of message to watch for.

    • listener: ((this, message) => void)

      The callback function.

    Returns void

addPropertyListener

  • addPropertyListener<K>(propertyName, listener): void

  • Adds the given listener function for the specified property.

    Type Parameters

    • K extends "name" | "rollState" | "batteryLevel" | "rssi" | "systemId" | "pixelId" | "ledCount" | "colorway" | "dieType" | "firmwareDate" | "isCharging" | "currentFace" | "currentFaceIndex"

    Parameters

    Returns void

blink

  • blink(color, opt?): Promise<void>

  • Requests the Pixel to blink and wait for a confirmation.

    Parameters

    • color: Color

      Blink color.

    • Optional opt: {
          count?: number;
          duration?: number;
          faceMask?: number;
          fade?: number;
          loopCount?: number;
      }
      • Optional count?: number

        Number of blinks.

      • Optional duration?: number

        Total duration of the animation in milliseconds.

      • Optional faceMask?: number

        Select which faces to light up.

      • Optional fade?: number

        Amount of in and out fading, 0: sharp transition, 1: maximum fading.

      • Optional loopCount?: number

        How many times to loop the animation.

    Returns Promise<void>

    A promise that resolves once the die has confirmed receiving the message.

connect

  • connect(timeoutMs?): Promise<Pixel>

  • Asynchronously tries to connect to the die. Throws on connection error.

    Parameters

    • Optional timeoutMs: number

      Delay before giving up (may be ignored when having concurrent calls to connect()). It may take longer than the given timeout for the function to return.

    Returns Promise<Pixel>

    A promise that resoles to this instance once the connection process has completed (whether successfully or not).

    Throws

    Will throw a PixelConnectError if it fails to connect in time.

disconnect

  • disconnect(): Promise<Pixel>

  • Immediately disconnects from the die.

    Returns Promise<Pixel>

    A promise that resolves once the disconnect request has been processed.

Protected emitPropertyEvent

  • emitPropertyEvent<K>(propertyName): void

  • Emit a Pixel event for the specified property. This function should be called by the concrete type whenever the a property's value changes.

    Type Parameters

    • K extends "name" | "rollState" | "batteryLevel" | "rssi" | "systemId" | "pixelId" | "ledCount" | "colorway" | "dieType" | "firmwareDate" | "isCharging" | "currentFace" | "currentFaceIndex"

    Parameters

    • propertyName: K

      Event name.

    Returns void

playInstantAnimation

  • playInstantAnimation(animIndex): Promise<void>

  • Plays the instant animation at the given index. See

    Parameters

    • animIndex: number

      The index of the instant animation to play.

    Returns Promise<void>

    A promise that resolves once the message has been send.

    See

    transferInstantAnimations().

playTestAnimation

  • playTestAnimation(dataSet, progressCallback?): Promise<void>

  • Plays the (single) LEDs animation included in the given data set.

    Parameters

    • dataSet: DataSet

      The data set containing just one animation to play.

    • Optional progressCallback: ((progress) => void)

      An optional callback that is called as the operation progresses with the progress in percent..

        • (progress): void

        • Parameters

          • progress: number

          Returns void

    Returns Promise<void>

    A promise that resolves once the transfer has completed.

queryRssi

  • queryRssi(): Promise<number>

  • Asynchronously gets the battery state.

    Returns Promise<number>

    A promise revolving to an object with the batter level in percentage and flag indicating whether it is charging or not.

removeEventListener

  • removeEventListener<K>(type, listener): void

  • Unregisters a listener from receiving events identified by the given event name. See PixelEventMap for the list of events and their associated data.

    Type Parameters

    Parameters

    Returns void

removeMessageListener

  • removeMessageListener(msgType, listener): void

  • Unregisters a listener from receiving raw messages of a given type.

    Parameters

    • msgType: "blink" | "none" | "whoAreYou" | "iAmADie" | "rollState" | "telemetry" | "bulkSetup" | "bulkSetupAck" | "bulkData" | "bulkDataAck" | "transferAnimationSet" | "transferAnimationSetAck" | "transferAnimationSetFinished" | "transferSettings" | "transferSettingsAck" | "transferSettingsFinished" | "transferTestAnimationSet" | "transferTestAnimationSetAck" | "transferTestAnimationSetFinished" | "debugLog" | "playAnimation" | "playAnimationEvent" | "stopAnimation" | "remoteAction" | "requestRollState" | "requestAnimationSet" | "requestSettings" | "requestTelemetry" | "programDefaultAnimationSet" | "programDefaultAnimationSetFinished" | "blinkAck" | "requestDefaultAnimationSetColor" | "defaultAnimationSetColor" | "requestBatteryLevel" | "batteryLevel" | "requestRssi" | "rssi" | "calibrate" | "calibrateFace" | "notifyUser" | "notifyUserAck" | "testHardware" | "storeValue" | "storeValueAck" | "setTopLevelState" | "programDefaultParameters" | "programDefaultParametersFinished" | "setDesignAndColor" | "setDesignAndColorAck" | "setCurrentBehavior" | "setCurrentBehaviorAck" | "setName" | "setNameAck" | "powerOperation" | "exitValidation" | "transferInstantAnimationSet" | "transferInstantAnimationSetAck" | "transferInstantAnimationSetFinished" | "playInstantAnimation" | "stopAllAnimations" | "requestTemperature" | "temperature" | "setBatteryControllerMode" | "_unused" | "discharge" | "blinkId" | "blinkIdAck" | "transferTest" | "transferTestAck" | "transferTestFinished" | "clearSettings" | "clearSettingsAck" | "testBulkSend" | "testBulkReceive" | "setAllLEDsToColor" | "attractMode" | "printNormals" | "printA2DReadings" | "lightUpFace" | "setLEDToColor" | "debugAnimationController"

      The type of message to watch for.

    • listener: ((this, msg) => void)

      The callback function to unregister.

    Returns void

removePropertyListener

  • removePropertyListener<K>(propertyName, listener): void

  • Removes the given listener function for the specified property.

    Type Parameters

    • K extends "name" | "rollState" | "batteryLevel" | "rssi" | "systemId" | "pixelId" | "ledCount" | "colorway" | "dieType" | "firmwareDate" | "isCharging" | "currentFace" | "currentFaceIndex"

    Parameters

    Returns void

rename

  • rename(name): Promise<void>

  • Requests the Pixel to change its name.

    Parameters

    • name: string

      New name to assign to the Pixel. Must have at least one character.

    Returns Promise<void>

    A promise that resolves once the die has confirmed being renamed.

reportRssi

  • reportRssi(activate, minInterval?): Promise<void>

  • Requests the Pixel to regularly send its measured RSSI value.

    Parameters

    • activate: boolean

      Whether to turn or turn off this feature.

    • Optional minInterval: number

      The minimum time interval in milliseconds between two RSSI updates.

    Returns Promise<void>

    A promise that resolves once the message has been send.

sendAndWaitForResponse

  • sendAndWaitForResponse(msgOrTypeToSend, responseType, timeoutMs?): Promise<MessageOrType>

  • Sends a message to the Pixel and wait for a specific response.

    Parameters

    • msgOrTypeToSend: MessageOrType

      Message with the data to send or just a message type.

    • responseType: "blink" | "none" | "whoAreYou" | "iAmADie" | "rollState" | "telemetry" | "bulkSetup" | "bulkSetupAck" | "bulkData" | "bulkDataAck" | "transferAnimationSet" | "transferAnimationSetAck" | "transferAnimationSetFinished" | "transferSettings" | "transferSettingsAck" | "transferSettingsFinished" | "transferTestAnimationSet" | "transferTestAnimationSetAck" | "transferTestAnimationSetFinished" | "debugLog" | "playAnimation" | "playAnimationEvent" | "stopAnimation" | "remoteAction" | "requestRollState" | "requestAnimationSet" | "requestSettings" | "requestTelemetry" | "programDefaultAnimationSet" | "programDefaultAnimationSetFinished" | "blinkAck" | "requestDefaultAnimationSetColor" | "defaultAnimationSetColor" | "requestBatteryLevel" | "batteryLevel" | "requestRssi" | "rssi" | "calibrate" | "calibrateFace" | "notifyUser" | "notifyUserAck" | "testHardware" | "storeValue" | "storeValueAck" | "setTopLevelState" | "programDefaultParameters" | "programDefaultParametersFinished" | "setDesignAndColor" | "setDesignAndColorAck" | "setCurrentBehavior" | "setCurrentBehaviorAck" | "setName" | "setNameAck" | "powerOperation" | "exitValidation" | "transferInstantAnimationSet" | "transferInstantAnimationSetAck" | "transferInstantAnimationSetFinished" | "playInstantAnimation" | "stopAllAnimations" | "requestTemperature" | "temperature" | "setBatteryControllerMode" | "_unused" | "discharge" | "blinkId" | "blinkIdAck" | "transferTest" | "transferTestAck" | "transferTestFinished" | "clearSettings" | "clearSettingsAck" | "testBulkSend" | "testBulkReceive" | "setAllLEDsToColor" | "attractMode" | "printNormals" | "printA2DReadings" | "lightUpFace" | "setLEDToColor" | "debugAnimationController"

      Expected response type.

    • Optional timeoutMs: number

      Timeout in mill-seconds before aborting waiting for the response.

    Returns Promise<MessageOrType>

    A promise resolving to the response in the form of a message type or a message object.

sendAndWaitForTypedResponse

  • sendAndWaitForTypedResponse<T>(msgOrTypeToSend, responseType, timeoutMs?): Promise<T>

  • Sends a message to the Pixel and wait for a specific response which is returned casted to the expected type.

    Type Parameters

    Parameters

    • msgOrTypeToSend: MessageOrType

      Message with the data to send or just a message type.

    • responseType: (new () => T)

      Expected response class type.

        • new (): T

        • Returns T

    • Optional timeoutMs: number

    Returns Promise<T>

    A promise resolving to a message object of the expected type.

sendMessage

  • sendMessage(msgOrType, withoutAck?): Promise<void>

  • Sends a message to the Pixel.

    Parameters

    • msgOrType: MessageOrType

      Message with the data to send or just a message type.

    • Optional withoutAck: boolean

      Whether to request a confirmation that the message was received.

    Returns Promise<void>

    A promise that resolves once the message has been send.

startCalibration

  • startCalibration(): Promise<void>

  • Requests the Pixel to start faces calibration sequence.

    Returns Promise<void>

    A promise that resolves once the message has been send.

stopAllAnimations

  • stopAllAnimations(): Promise<void>

  • Requests the Pixel to stop all currently playing animations.

    Returns Promise<void>

    A promise.

transferDataSet

  • transferDataSet(dataSet, progressCallback?): Promise<void>

  • Uploads the given data set of animations to the Pixel flash memory.

    Parameters

    • dataSet: DataSet

      The data set to upload.

    • Optional progressCallback: ((progress) => void)

      An optional callback that is called as the operation progresses with the progress in percent..

        • (progress): void

        • Parameters

          • progress: number

          Returns void

    Returns Promise<void>

    A promise that resolves once the transfer has completed.

transferInstantAnimations

  • transferInstantAnimations(dataSet, progressCallback?): Promise<void>

  • Uploads the given data set of animations to the Pixel RAM memory. Those animations are lost when the Pixel goes to sleep, is turned off or is restarted.

    Parameters

    • dataSet: DataSet

      The data set to upload.

    • Optional progressCallback: ((progress) => void)

      An optional callback that is called as the operation progresses with the progress in percent..

        • (progress): void

        • Parameters

          • progress: number

          Returns void

    Returns Promise<void>

    A promise that resolves once the transfer has completed.

turnOff

  • turnOff(): Promise<void>

  • Requests the Pixel to completely turn off.

    Returns Promise<void>

    A promise that resolves once the message has been send.

updateInfo

  • updateInfo(info): void

  • Update Pixel info from an external source such as scanning data.

    Parameters

    • info: Partial<Omit<PixelInfo, "currentFace">>

      The updated info.

    Returns void

    Remarks

    The info will be updated only if the die is disconnected. Roll state and face index are updated only if both are provided.

uploadBulkDataWithAck

  • uploadBulkDataWithAck(ackType, data, progressCallback?, progressMode?): Promise<void>

  • Upload the given data to the Pixel.

    Parameters

    • ackType: "blink" | "none" | "whoAreYou" | "iAmADie" | "rollState" | "telemetry" | "bulkSetup" | "bulkSetupAck" | "bulkData" | "bulkDataAck" | "transferAnimationSet" | "transferAnimationSetAck" | "transferAnimationSetFinished" | "transferSettings" | "transferSettingsAck" | "transferSettingsFinished" | "transferTestAnimationSet" | "transferTestAnimationSetAck" | "transferTestAnimationSetFinished" | "debugLog" | "playAnimation" | "playAnimationEvent" | "stopAnimation" | "remoteAction" | "requestRollState" | "requestAnimationSet" | "requestSettings" | "requestTelemetry" | "programDefaultAnimationSet" | "programDefaultAnimationSetFinished" | "blinkAck" | "requestDefaultAnimationSetColor" | "defaultAnimationSetColor" | "requestBatteryLevel" | "batteryLevel" | "requestRssi" | "rssi" | "calibrate" | "calibrateFace" | "notifyUser" | "notifyUserAck" | "testHardware" | "storeValue" | "storeValueAck" | "setTopLevelState" | "programDefaultParameters" | "programDefaultParametersFinished" | "setDesignAndColor" | "setDesignAndColorAck" | "setCurrentBehavior" | "setCurrentBehaviorAck" | "setName" | "setNameAck" | "powerOperation" | "exitValidation" | "transferInstantAnimationSet" | "transferInstantAnimationSetAck" | "transferInstantAnimationSetFinished" | "playInstantAnimation" | "stopAllAnimations" | "requestTemperature" | "temperature" | "setBatteryControllerMode" | "_unused" | "discharge" | "blinkId" | "blinkIdAck" | "transferTest" | "transferTestAck" | "transferTestFinished" | "clearSettings" | "clearSettingsAck" | "testBulkSend" | "testBulkReceive" | "setAllLEDsToColor" | "attractMode" | "printNormals" | "printA2DReadings" | "lightUpFace" | "setLEDToColor" | "debugAnimationController"

      The expected confirmation message type.

    • data: ArrayBuffer

      The data to send.

    • Optional progressCallback: ((progress) => void)

      An optional callback that is called as the operation progresses with the progress in percent..

        • (progress): void

        • Parameters

          • progress: number

          Returns void

    • Optional progressMode: "percent" | "bytes"

      Whether to notify progress in percent or bytes.

    Returns Promise<void>

    A promise that resolves once the transfer has completed.

Settings

Member Visibility

Theme

On This Page

Generated using TypeDoc