Momentum-Apps/mp_flipper/docs/pages/reference.rst

Reference
=========

This page contains the API documentation of the ``flipperzero`` module and some built-in functions.
The module is also available as a Python package on `PyPI <https://pypi.org/project/flipperzero/>`_.
Install it in your local development environment if you need code completion support inside your IDE.

Vibration
---------

Control the vibration motor of your Flipper.

.. autofunction:: flipperzero.vibro_set

.. _reference-light:

Light
-----

Control the RGB LED and display backlight of your Flipper.

Constants
~~~~~~~~~

.. autodata:: flipperzero.LIGHT_RED
.. autodata:: flipperzero.LIGHT_GREEN
.. autodata:: flipperzero.LIGHT_BLUE
.. autodata:: flipperzero.LIGHT_BACKLIGHT

Functions
~~~~~~~~~

.. autofunction:: flipperzero.light_set
.. autofunction:: flipperzero.light_blink_start
.. autofunction:: flipperzero.light_blink_set_color
.. autofunction:: flipperzero.light_blink_stop

.. _reference-speaker:

Speaker
-------

Full control over the built-in speaker module.

Musical Notes
~~~~~~~~~~~~~

..
   for octave in range(9):
      for name in ['C', 'CS', 'D', 'DS', 'E', 'F', 'FS', 'G', 'GS', 'A', 'AS', 'B']:
         print(f'.. autodata:: flipperzero.SPEAKER_NOTE_{name}{octave}')

.. autodata:: flipperzero.SPEAKER_NOTE_C0
.. autodata:: flipperzero.SPEAKER_NOTE_CS0
.. autodata:: flipperzero.SPEAKER_NOTE_D0
.. autodata:: flipperzero.SPEAKER_NOTE_DS0
.. autodata:: flipperzero.SPEAKER_NOTE_E0
.. autodata:: flipperzero.SPEAKER_NOTE_F0
.. autodata:: flipperzero.SPEAKER_NOTE_FS0
.. autodata:: flipperzero.SPEAKER_NOTE_G0
.. autodata:: flipperzero.SPEAKER_NOTE_GS0
.. autodata:: flipperzero.SPEAKER_NOTE_A0
.. autodata:: flipperzero.SPEAKER_NOTE_AS0
.. autodata:: flipperzero.SPEAKER_NOTE_B0
.. autodata:: flipperzero.SPEAKER_NOTE_C1
.. autodata:: flipperzero.SPEAKER_NOTE_CS1
.. autodata:: flipperzero.SPEAKER_NOTE_D1
.. autodata:: flipperzero.SPEAKER_NOTE_DS1
.. autodata:: flipperzero.SPEAKER_NOTE_E1
.. autodata:: flipperzero.SPEAKER_NOTE_F1
.. autodata:: flipperzero.SPEAKER_NOTE_FS1
.. autodata:: flipperzero.SPEAKER_NOTE_G1
.. autodata:: flipperzero.SPEAKER_NOTE_GS1
.. autodata:: flipperzero.SPEAKER_NOTE_A1
.. autodata:: flipperzero.SPEAKER_NOTE_AS1
.. autodata:: flipperzero.SPEAKER_NOTE_B1
.. autodata:: flipperzero.SPEAKER_NOTE_C2
.. autodata:: flipperzero.SPEAKER_NOTE_CS2
.. autodata:: flipperzero.SPEAKER_NOTE_D2
.. autodata:: flipperzero.SPEAKER_NOTE_DS2
.. autodata:: flipperzero.SPEAKER_NOTE_E2
.. autodata:: flipperzero.SPEAKER_NOTE_F2
.. autodata:: flipperzero.SPEAKER_NOTE_FS2
.. autodata:: flipperzero.SPEAKER_NOTE_G2
.. autodata:: flipperzero.SPEAKER_NOTE_GS2
.. autodata:: flipperzero.SPEAKER_NOTE_A2
.. autodata:: flipperzero.SPEAKER_NOTE_AS2
.. autodata:: flipperzero.SPEAKER_NOTE_B2
.. autodata:: flipperzero.SPEAKER_NOTE_C3
.. autodata:: flipperzero.SPEAKER_NOTE_CS3
.. autodata:: flipperzero.SPEAKER_NOTE_D3
.. autodata:: flipperzero.SPEAKER_NOTE_DS3
.. autodata:: flipperzero.SPEAKER_NOTE_E3
.. autodata:: flipperzero.SPEAKER_NOTE_F3
.. autodata:: flipperzero.SPEAKER_NOTE_FS3
.. autodata:: flipperzero.SPEAKER_NOTE_G3
.. autodata:: flipperzero.SPEAKER_NOTE_GS3
.. autodata:: flipperzero.SPEAKER_NOTE_A3
.. autodata:: flipperzero.SPEAKER_NOTE_AS3
.. autodata:: flipperzero.SPEAKER_NOTE_B3
.. autodata:: flipperzero.SPEAKER_NOTE_C4
.. autodata:: flipperzero.SPEAKER_NOTE_CS4
.. autodata:: flipperzero.SPEAKER_NOTE_D4
.. autodata:: flipperzero.SPEAKER_NOTE_DS4
.. autodata:: flipperzero.SPEAKER_NOTE_E4
.. autodata:: flipperzero.SPEAKER_NOTE_F4
.. autodata:: flipperzero.SPEAKER_NOTE_FS4
.. autodata:: flipperzero.SPEAKER_NOTE_G4
.. autodata:: flipperzero.SPEAKER_NOTE_GS4
.. autodata:: flipperzero.SPEAKER_NOTE_A4
.. autodata:: flipperzero.SPEAKER_NOTE_AS4
.. autodata:: flipperzero.SPEAKER_NOTE_B4
.. autodata:: flipperzero.SPEAKER_NOTE_C5
.. autodata:: flipperzero.SPEAKER_NOTE_CS5
.. autodata:: flipperzero.SPEAKER_NOTE_D5
.. autodata:: flipperzero.SPEAKER_NOTE_DS5
.. autodata:: flipperzero.SPEAKER_NOTE_E5
.. autodata:: flipperzero.SPEAKER_NOTE_F5
.. autodata:: flipperzero.SPEAKER_NOTE_FS5
.. autodata:: flipperzero.SPEAKER_NOTE_G5
.. autodata:: flipperzero.SPEAKER_NOTE_GS5
.. autodata:: flipperzero.SPEAKER_NOTE_A5
.. autodata:: flipperzero.SPEAKER_NOTE_AS5
.. autodata:: flipperzero.SPEAKER_NOTE_B5
.. autodata:: flipperzero.SPEAKER_NOTE_C6
.. autodata:: flipperzero.SPEAKER_NOTE_CS6
.. autodata:: flipperzero.SPEAKER_NOTE_D6
.. autodata:: flipperzero.SPEAKER_NOTE_DS6
.. autodata:: flipperzero.SPEAKER_NOTE_E6
.. autodata:: flipperzero.SPEAKER_NOTE_F6
.. autodata:: flipperzero.SPEAKER_NOTE_FS6
.. autodata:: flipperzero.SPEAKER_NOTE_G6
.. autodata:: flipperzero.SPEAKER_NOTE_GS6
.. autodata:: flipperzero.SPEAKER_NOTE_A6
.. autodata:: flipperzero.SPEAKER_NOTE_AS6
.. autodata:: flipperzero.SPEAKER_NOTE_B6
.. autodata:: flipperzero.SPEAKER_NOTE_C7
.. autodata:: flipperzero.SPEAKER_NOTE_CS7
.. autodata:: flipperzero.SPEAKER_NOTE_D7
.. autodata:: flipperzero.SPEAKER_NOTE_DS7
.. autodata:: flipperzero.SPEAKER_NOTE_E7
.. autodata:: flipperzero.SPEAKER_NOTE_F7
.. autodata:: flipperzero.SPEAKER_NOTE_FS7
.. autodata:: flipperzero.SPEAKER_NOTE_G7
.. autodata:: flipperzero.SPEAKER_NOTE_GS7
.. autodata:: flipperzero.SPEAKER_NOTE_A7
.. autodata:: flipperzero.SPEAKER_NOTE_AS7
.. autodata:: flipperzero.SPEAKER_NOTE_B7
.. autodata:: flipperzero.SPEAKER_NOTE_C8
.. autodata:: flipperzero.SPEAKER_NOTE_CS8
.. autodata:: flipperzero.SPEAKER_NOTE_D8
.. autodata:: flipperzero.SPEAKER_NOTE_DS8
.. autodata:: flipperzero.SPEAKER_NOTE_E8
.. autodata:: flipperzero.SPEAKER_NOTE_F8
.. autodata:: flipperzero.SPEAKER_NOTE_FS8
.. autodata:: flipperzero.SPEAKER_NOTE_G8
.. autodata:: flipperzero.SPEAKER_NOTE_GS8
.. autodata:: flipperzero.SPEAKER_NOTE_A8
.. autodata:: flipperzero.SPEAKER_NOTE_AS8
.. autodata:: flipperzero.SPEAKER_NOTE_B8

Volume
~~~~~~

.. autodata:: flipperzero.SPEAKER_VOLUME_MIN
.. autodata:: flipperzero.SPEAKER_VOLUME_MAX

Functions
~~~~~~~~~

.. autofunction:: flipperzero.speaker_start
.. autofunction:: flipperzero.speaker_set_volume
.. autofunction:: flipperzero.speaker_stop

.. _reference-input:

Input
-----

Make your application interactive with full control over the Flipper's hardware buttons.

Buttons
~~~~~~~

.. autodata:: flipperzero.INPUT_BUTTON_UP
.. autodata:: flipperzero.INPUT_BUTTON_DOWN
.. autodata:: flipperzero.INPUT_BUTTON_RIGHT
.. autodata:: flipperzero.INPUT_BUTTON_LEFT
.. autodata:: flipperzero.INPUT_BUTTON_OK
.. autodata:: flipperzero.INPUT_BUTTON_BACK

Events
~~~~~~

.. autodata:: flipperzero.INPUT_TYPE_PRESS
.. autodata:: flipperzero.INPUT_TYPE_RELEASE
.. autodata:: flipperzero.INPUT_TYPE_SHORT
.. autodata:: flipperzero.INPUT_TYPE_LONG
.. autodata:: flipperzero.INPUT_TYPE_REPEAT

Functions
~~~~~~~~~

.. autodecorator:: flipperzero.on_input

.. _reference-canvas:

Canvas
------

Write text and draw dots and shapes on the the display.

Basics
~~~~~~

.. autofunction:: flipperzero.canvas_update
.. autofunction:: flipperzero.canvas_clear
.. autofunction:: flipperzero.canvas_width
.. autofunction:: flipperzero.canvas_height

Colors
~~~~~~

.. autodata:: flipperzero.COLOR_BLACK
.. autodata:: flipperzero.COLOR_WHITE
.. autofunction:: flipperzero.canvas_set_color

Alignment
~~~~~~~~~

.. autodata:: flipperzero.ALIGN_BEGIN
.. autodata:: flipperzero.ALIGN_END
.. autodata:: flipperzero.ALIGN_CENTER
.. autofunction:: flipperzero.canvas_set_text_align

Text
~~~~

.. autodata:: flipperzero.FONT_PRIMARY
.. autodata:: flipperzero.FONT_SECONDARY
.. autofunction:: flipperzero.canvas_set_font
.. autofunction:: flipperzero.canvas_set_text

Shapes
~~~~~~

.. autofunction:: flipperzero.canvas_draw_dot
.. autofunction:: flipperzero.canvas_draw_box
.. autofunction:: flipperzero.canvas_draw_frame
.. autofunction:: flipperzero.canvas_draw_line
.. autofunction:: flipperzero.canvas_draw_circle
.. autofunction:: flipperzero.canvas_draw_disc

Dialog
------

Display message dialogs on the display for user infos and confirm actions.

.. autofunction:: flipperzero.dialog_message_set_header
.. autofunction:: flipperzero.dialog_message_set_text
.. autofunction:: flipperzero.dialog_message_set_button
.. autofunction:: flipperzero.dialog_message_show

.. _reference-gpio:

GPIO
----

Access to the GPIO pins of your Flipper.

Pins
~~~~

.. autodata:: flipperzero.GPIO_PIN_PC0
.. autodata:: flipperzero.GPIO_PIN_PC1
.. autodata:: flipperzero.GPIO_PIN_PC3
.. autodata:: flipperzero.GPIO_PIN_PB2
.. autodata:: flipperzero.GPIO_PIN_PB3
.. autodata:: flipperzero.GPIO_PIN_PA4
.. autodata:: flipperzero.GPIO_PIN_PA6
.. autodata:: flipperzero.GPIO_PIN_PA7

Modes
~~~~~

.. autodata:: flipperzero.GPIO_MODE_INPUT
.. autodata:: flipperzero.GPIO_MODE_OUTPUT_PUSH_PULL
.. autodata:: flipperzero.GPIO_MODE_OUTPUT_OPEN_DRAIN
.. autodata:: flipperzero.GPIO_MODE_ANALOG
.. autodata:: flipperzero.GPIO_MODE_INTERRUPT_RISE
.. autodata:: flipperzero.GPIO_MODE_INTERRUPT_FALL

Pull 
~~~~

.. autodata:: flipperzero.GPIO_PULL_NO
.. autodata:: flipperzero.GPIO_PULL_UP
.. autodata:: flipperzero.GPIO_PULL_DOWN

Speed
~~~~~

.. autodata:: flipperzero.GPIO_SPEED_LOW
.. autodata:: flipperzero.GPIO_SPEED_MEDIUM
.. autodata:: flipperzero.GPIO_SPEED_HIGH
.. autodata:: flipperzero.GPIO_SPEED_VERY_HIGH

Functions
~~~~~~~~~

.. autofunction:: flipperzero.gpio_init_pin
.. autofunction:: flipperzero.gpio_deinit_pin
.. autofunction:: flipperzero.gpio_set_pin
.. autofunction:: flipperzero.gpio_get_pin
.. autodecorator:: flipperzero.on_gpio

.. _reference-adc:

ADC
---

Read analog values from selected GPIO pins:

* :const:`flipperzero.GPIO_PIN_PC0`
* :const:`flipperzero.GPIO_PIN_PC1`
* :const:`flipperzero.GPIO_PIN_PC3`
* :const:`flipperzero.GPIO_PIN_PA4`
* :const:`flipperzero.GPIO_PIN_PA6`
* :const:`flipperzero.GPIO_PIN_PA7`

The corresponding pin must be initialized in the analog mode:

.. code-block::

   import flipperzero as f0

   f0.gpio_init_pin(f0.GPIO_PIN_PC0, f0.GPIO_MODE_ANALOG)

This configures the pin as ADC input with the following settings:

* Reference voltage is set to 2.048 V.
* Clock speed is at 64 MHz in synchronous mode.
* Oversample rate is set to 64.

`This default configuration is best for relatively high impedance circuits with slowly or or not changing signals.`

Functions
~~~~~~~~~

.. autofunction:: flipperzero.adc_read_pin_value
.. autofunction:: flipperzero.adc_read_pin_voltage

.. _reference-pwm:

PWM
---

Output a PWM signal on selected GPIO pins:

* :const:`flipperzero.GPIO_PIN_PA4`
* :const:`flipperzero.GPIO_PIN_PA7`

Functions
~~~~~~~~~

.. autofunction:: flipperzero.pwm_start
.. autofunction:: flipperzero.pwm_stop
.. autofunction:: flipperzero.pwm_is_running

.. _reference-infrared:

Infrared
--------

Send and receive infrared signals.

Signal Format
~~~~~~~~~~~~~

The format to represent infrared signals uses a simple list of integers.
Each value represents the duration between two signal edges in microseconds.
Since this is a digital signal, there are only two levels: `high` and `low`.
The timing list always starts with a `high` level.

.. literalinclude:: ./assets/pwm_signal.txt
   :language: text

.. hint::

   This is equal to the raw signal format of the `IR file <https://developer.flipper.net/flipperzero/doxygen/infrared_file_format.html>`_ specification.

Functions
~~~~~~~~~

.. autofunction:: flipperzero.infrared_receive
.. autofunction:: flipperzero.infrared_transmit
.. autofunction:: flipperzero.infrared_is_busy

UART
----

Connect to UART enabled devices.

Modes
~~~~~

.. autodata:: flipperzero.UART_MODE_LPUART
.. autodata:: flipperzero.UART_MODE_USART

Functions
~~~~~~~~~

.. autofunction:: flipperzero.uart_open

Classes
~~~~~~~

.. autoclass:: flipperzero.UART
   :members: read, readline, readlines, write, flush, close, __enter__, __exit__, __del__

Logging
-------

Log messages to the Flipper's own logging backend.
Check out the `Flipper Zero docs <https://docs.flipper.net/development/cli#_yZ2E>`_ on how to reveal them in the CLI.
Be aware, that you can't change Flipper's global log level from within your script.
Change the `corresponding settings <https://docs.flipper.net/basics/settings#d5TAt>`_ instead or use the **log** command in the CLI with the desired log level as the first argument.

Levels
~~~~~~

.. autodata:: logging.TRACE
.. autodata:: logging.DEBUG
.. autodata:: logging.INFO
.. autodata:: logging.WARN
.. autodata:: logging.ERROR
.. autodata:: logging.NONE
.. autodata:: logging.level

Functions
~~~~~~~~~

.. autofunction:: logging.setLevel
.. autofunction:: logging.getEffectiveLevel
.. autofunction:: logging.trace
.. autofunction:: logging.debug
.. autofunction:: logging.info
.. autofunction:: logging.warn
.. autofunction:: logging.error
.. autofunction:: logging.log

I/O
---

Read and write files on the SD card.

Constants
~~~~~~~~~

.. autodata:: io.SEEK_SET
.. autodata:: io.SEEK_CUR
.. autodata:: io.SEEK_END

Functions
~~~~~~~~~

.. autofunction:: io.open

Classes
~~~~~~~

.. autoclass:: io.BinaryFileIO
   :members: name, read, readline, readlines, readable, writable, write, flush, seek, tell, close, __enter__, __exit__, __del__

.. autoclass:: io.TextFileIO
   :members: name, read, readline, readlines, readable, writable, write, flush, seek, tell, close, __enter__, __exit__, __del__

Built-In
--------

The functions in this section are `not` part of the ``flipperzero`` module.
They're members of the global namespace instead.

.. py:function:: print(*objects, sep=' ', end='\n') -> None

   The standard Python `print <https://docs.python.org/3/library/functions.html#print>`_ function.
   Where the output of this function will be redirected depends on how the script is invoked:

      * When invoked from the UI, the output will be sent to the Flipper's log buffer.
        Check out the `Flipper Zero docs <https://docs.flipper.net/development/cli#_yZ2E>`_ on how to view them in the CLI interface.
      * In the REPL, the output will be sent to the standard output buffer.
      * When invoked by the **py** command, the output will be sent to the standard output buffer.

   :param objects: The objects to print (mostly a single string).
   :param sep: The separator to use between the objects.
   :param end: The line terminator character to use.

   .. versionadded:: 1.0.0
   .. versionchanged:: 1.5.0

      Output redirection, based on script invocation.