def play(music, pin="microbit.pin0", wait=True, loop=False):
"""
This function is not implemented in the simulator.
Plays ``music`` containing the musical DSL defined above.
If ``music`` is a string it is expected to be a single note such as,
``'c1:4'``.
If ``music`` is specified as a list of notes (as defined in the section on
the musical DSL, above) then they are played one after the other to perform
a melody.
In both cases, the ``duration`` and ``octave`` values are reset to
their defaults before the music (whatever it may be) is played.
An optional argument to specify the output pin can be used to override the
default of ``microbit.pin0``.
If ``wait`` is set to ``True``, this function is blocking.
If ``loop`` is set to ``True``, the tune repeats until ``stop`` is called
(see below) or the blocking call is interrupted.
"""
utils.print_for_unimplemented_functions(play.__name__)
telemetry_py.send_telemetry(TelemetryEvent.MICROBIT_API_MUSIC)
def ticks_add(ticks, delta):
"""
This function is not implemented in the simulator.
Offset ticks value by a given number, which can be either positive or
negative. Given a ticks value, this function allows to calculate ticks
value delta ticks before or after it, following modular-arithmetic
definition of tick values.
Example:
.. code-block:: python
# Find out what ticks value there was 100ms ago
print(ticks_add(time.ticks_ms(), -100))
# Calculate deadline for operation and test for it
deadline = ticks_add(time.ticks_ms(), 200)
while ticks_diff(deadline, time.ticks_ms()) > 0:
do_a_little_of_something()
# Find out TICKS_MAX used by this port
print(ticks_add(0, -1))
"""
utils.print_for_unimplemented_functions(ticks_add.__name__)
telemetry_py.send_telemetry(TelemetryEvent.MICROBIT_API_UTIME)
def receive_full():
"""
This function is not implemented in the simulator.
Returns a tuple containing three values representing the next incoming
message on the message queue. If there are no pending messages then
``None`` is returned.
The three values in the tuple represent:
* the next incoming message on the message queue as bytes.
* the RSSI (signal strength): a value between 0 (strongest) and -255 (weakest) as measured in dBm.
* a microsecond timestamp: the value returned by ``time.ticks_us()`` when the message was received.
For example::
details = radio.receive_full()
if details:
msg, rssi, timestamp = details
This function is useful for providing information needed for triangulation
and/or triliteration with other micro:bit devices.
"""
utils.print_for_unimplemented_functions(receive_full.__name__)
telemetry_py.send_telemetry(TelemetryEvent.MICROBIT_API_RADIO)
def __init__(self,
pin,
*,
duty_cycle=0,
frequency=500,
variable_frequency=False):
utils.print_for_unimplemented_functions(PWMOut.__init__.__qualname__)
def init(baudrate=1000000,
bits=8,
mode=0,
sclk="pin13",
mosi="pin15",
miso="pin14"):
"""
This function is not implemented in the simulator.
Initialize SPI communication with the specified parameters on the
specified ``pins``. Note that for correct communication, the parameters
have to be the same on both communicating devices.
The ``baudrate`` defines the speed of communication.
The ``bits`` defines the size of bytes being transmitted. Currently only
``bits=8`` is supported. However, this may change in the future.
The ``mode`` determines the combination of clock polarity and phase
according to the following convention, with polarity as the high order bit
and phase as the low order bit:
Polarity (aka CPOL) 0 means that the clock is at logic value 0 when idle
and goes high (logic value 1) when active; polarity 1 means the clock is
at logic value 1 when idle and goes low (logic value 0) when active. Phase
(aka CPHA) 0 means that data is sampled on the leading edge of the clock,
and 1 means on the trailing edge.
The ``sclk``, ``mosi`` and ``miso`` arguments specify the pins to use for
each type of signal.
"""
utils.print_for_unimplemented_functions(SPI.init.__qualname__)
telemetry_py.send_telemetry(TelemetryEvent.MICROBIT_API_SPI)
def adjust_touch_threshold(self, adjustment):
"""Not implemented!
The CPX Simulator doesn't use capacitive touch threshold.
"""
telemetry_py.send_telemetry(TelemetryEvent.CPX_API_ADJUST_THRESHOLD)
utils.print_for_unimplemented_functions(
Express.adjust_touch_threshold.__name__)
def get_tempo():
"""
This function is not implemented in the simulator.
Gets the current tempo as a tuple of integers: ``(ticks, bpm)``.
"""
utils.print_for_unimplemented_functions(get_tempo.__name__)
telemetry_py.send_telemetry(TelemetryEvent.MICROBIT_API_MUSIC)
def ticks_us():
"""
This function is not implemented in the simulator.
Just like :func:`utime.ticks_ms()` above, but in microseconds.
"""
utils.print_for_unimplemented_functions(ticks_us.__name__)
telemetry_py.send_telemetry(TelemetryEvent.MICROBIT_API_UTIME)
def off():
"""
This function is not implemented in the simulator.
Turns off the radio, thus saving power and memory
"""
utils.print_for_unimplemented_functions(off.__name__)
telemetry_py.send_telemetry(TelemetryEvent.MICROBIT_API_RADIO)
def clear_calibration(self):
"""
This function is not implemented in the simulator.
Undoes the calibration, making the compass uncalibrated again.
"""
utils.print_for_unimplemented_functions(Compass.clear_calibration.__name__)
telemetry_py.send_telemetry(TelemetryEvent.MICROBIT_API_COMPASS)
def read(self, nbytes):
"""
This function is not implemented in the simulator.
Read at most ``nbytes``. Returns what was read.
"""
utils.print_for_unimplemented_functions(SPI.read.__name__)
telemetry_py.send_telemetry(TelemetryEvent.MICROBIT_API_SPI)
def send_bytes(message):
"""
This function is not implemented in the simulator.
Sends a message containing bytes.
"""
utils.print_for_unimplemented_functions(send_bytes.__name__)
telemetry_py.send_telemetry(TelemetryEvent.MICROBIT_API_RADIO)
def calibrate(self):
"""
This function is not implemented in the simulator.
Starts the calibration process. When this function is called on the physical device, an instructive message will be scrolled to the user after which they will need to rotate the device in order to draw a circle on the LED display on the actual device.
"""
utils.print_for_unimplemented_functions(Compass.calibrate.__name__)
telemetry_py.send_telemetry(TelemetryEvent.MICROBIT_API_COMPASS)
def write(self, buffer):
"""
This function is not implemented in the simulator.
Write the ``buffer`` of bytes to the bus.
"""
utils.print_for_unimplemented_functions(SPI.write.__name__)
telemetry_py.send_telemetry(TelemetryEvent.MICROBIT_API_SPI)
def ticks_ms():
"""
This function is not implemented in the simulator.
Returns an increasing millisecond counter with an arbitrary reference point,
that wraps around after some value.
"""
utils.print_for_unimplemented_functions(ticks_ms.__name__)
telemetry_py.send_telemetry(TelemetryEvent.MICROBIT_API_UTIME)
def receive_bytes():
"""
This function is not implemented in the simulator.
Receive the next incoming message on the message queue. Returns ``None`` if
there are no pending messages. Messages are returned as bytes.
"""
utils.print_for_unimplemented_functions(receive_bytes.__name__)
telemetry_py.send_telemetry(TelemetryEvent.MICROBIT_API_RADIO)
def stop(pin="microbit.pin0"):
"""
This function is not implemented in the simulator.
Stops all music playback on a given pin, eg. ``music.stop(pin1)``.
If no pin is given, eg. ``music.stop()`` pin0 is assumed.
"""
utils.print_for_unimplemented_functions(stop.__name__)
telemetry_py.send_telemetry(TelemetryEvent.MICROBIT_API_MUSIC)
def reset():
"""
This function is not implemented in the simulator.
Reset the settings to their default values (as listed in the documentation
for the ``config`` function above).
"""
utils.print_for_unimplemented_functions(reset.__name__)
telemetry_py.send_telemetry(TelemetryEvent.MICROBIT_API_RADIO)
def on():
"""
This function is not implemented in the simulator.
Turns the radio on. This needs to be explicitly called since the radio
draws power and takes up memory that you may otherwise need.
"""
utils.print_for_unimplemented_functions(on.__name__)
telemetry_py.send_telemetry(TelemetryEvent.MICROBIT_API_RADIO)
def is_calibrated(self):
"""
This function is not implemented in the simulator.
Returns ``True`` if the compass has been successfully calibrated, and
returns ``False`` otherwise.
"""
utils.print_for_unimplemented_functions(Compass.is_calibrated.__name__)
telemetry_py.send_telemetry(TelemetryEvent.MICROBIT_API_COMPASS)
def get_field_strength(self):
"""
This function is not implemented in the simulator.
Returns an integer indication of the magnitude of the magnetic field around
the device in nano tesla.
"""
utils.print_for_unimplemented_functions(Compass.get_field_strength.__name__)
telemetry_py.send_telemetry(TelemetryEvent.MICROBIT_API_COMPASS)
def write(self, addr, buf, repeat=False):
"""
This function is not implemented in the simulator.
Write bytes from ``buf`` to the device with 7-bit address ``addr``. If
``repeat`` is ``True``, no stop bit will be sent.
"""
utils.print_for_unimplemented_functions(I2c.write.__name__)
telemetry_py.send_telemetry(TelemetryEvent.MICROBIT_API_I2C)
def scan(self):
"""
This function is not implemented in the simulator.
Scan the bus for devices. Returns a list of 7-bit addresses corresponding
to those devices that responded to the scan.
"""
utils.print_for_unimplemented_functions(I2c.scan.__name__)
telemetry_py.send_telemetry(TelemetryEvent.MICROBIT_API_I2C)
def write_readinto(self, out, in_):
"""
This function is not implemented in the simulator.
Write the ``out`` buffer to the bus and read any response into the ``in_``
buffer. The length of the buffers should be the same. The buffers can be
the same object.
"""
utils.print_for_unimplemented_functions(SPI.write_readinto.__name__)
telemetry_py.send_telemetry(TelemetryEvent.MICROBIT_API_SPI)
def heading(self):
"""
This function is not implemented in the simulator.
Gives the compass heading, calculated from the above readings, as an
integer in the range from 0 to 360, representing the angle in degrees,
clockwise, with north as 0.
"""
utils.print_for_unimplemented_functions(Compass.heading.__name__)
telemetry_py.send_telemetry(TelemetryEvent.MICROBIT_API_COMPASS)
def get_z(self):
"""
This function is not implemented in the simulator.
Gives the reading of the magnetic field strength on the ``z`` axis in nano
tesla, as a positive or negative integer, depending on the direction of the
field.
"""
utils.print_for_unimplemented_functions(Compass.get_z.__name__)
telemetry_py.send_telemetry(TelemetryEvent.MICROBIT_API_COMPASS)
def pronounce(phonemes, pitch=64, speed=72, mouth=128, throat=128):
"""
This function is not implemented in the simulator.
Pronounce the phonemes in the string ``phonemes``. See below for details of
how to use phonemes to finely control the output of the speech synthesiser.
Override the optional pitch, speed, mouth and throat settings to change the
timbre (quality) of the voice.
"""
utils.print_for_unimplemented_functions(pronounce.__name__)
telemetry_py.send_telemetry(TelemetryEvent.MICROBIT_API_SPEECH)
def sing(phonemes, pitch=64, speed=72, mouth=128, throat=128):
"""
This function is not implemented in the simulator.
Sing the phonemes contained in the string ``phonemes``. Changing the pitch
and duration of the note is described below. Override the optional pitch,
speed, mouth and throat settings to change the timbre (quality) of the
voice.
"""
utils.print_for_unimplemented_functions(sing.__name__)
telemetry_py.send_telemetry(TelemetryEvent.MICROBIT_API_SPEECH)
def receive_bytes_into(buffer):
"""
This function is not implemented in the simulator.
Receive the next incoming message on the message queue. Copies the message
into ``buffer``, trimming the end of the message if necessary.
Returns ``None`` if there are no pending messages, otherwise it returns the length
of the message (which might be more than the length of the buffer).
"""
utils.print_for_unimplemented_functions(receive_bytes_into.__name__)
telemetry_py.send_telemetry(TelemetryEvent.MICROBIT_API_RADIO)
def say(words, pitch=64, speed=72, mouth=128, throat=128):
"""
This function is not implemented in the simulator.
Say the English words in the string ``words``. The result is semi-accurate
for English. Override the optional pitch, speed, mouth and throat
settings to change the timbre (quality) of the voice. This is a short-hand
equivalent of: ``speech.pronounce(speech.translate(words))``
"""
utils.print_for_unimplemented_functions(say.__name__)
telemetry_py.send_telemetry(TelemetryEvent.MICROBIT_API_SPEECH)
