Skip to content

Latest commit

 

History

History
464 lines (292 loc) · 18.5 KB

PYTHON_REFERENCE.md

File metadata and controls

464 lines (292 loc) · 18.5 KB
Raw

RP2DAQ: Python API reference

This file was auto-generated by c_code_parser.py, using comments found in all include/*.c source files.

If not specified otherwise, all data types are integers.

Contents:

  1. identify
  2. gpio_out
  3. gpio_in
  4. gpio_on_change
  5. gpio_highz
  6. gpio_pull
  7. adc
  8. adc_stop
  9. pwm_configure_pair
  10. pwm_set_value
  11. stepper_init
  12. stepper_move
  13. stepper_status

identify

identify(flush_buffer=1,  _callback=None)

Mostly for internal use: confirms the RP2DAQ device is up and has matching firmware version

This command results in single near-immediate report.

Command parameters:

  • flush_buffer : Avoid possible pending messages from previous session (min=0, max=1, default=1)
  • _callback : Optionally, a function to handle future report(s). If set, makes this command asynchronous so it does not wait for the command being finished.

Report returns:

  • report_code : 0
  • data : as a list of integers.

gpio_out

gpio_out(gpio, value,  _callback=None)

Changes the output state of the specified gpio, i.e. general-purpose input/output pin. Depending on the "value=0" or "value=1" parameter, it connects the pin directly to 0 V, or 3.3 V, respectively.

This overrides previous high-impedance or pull-up/down state of the pin.

This command results in single, meaningless, near-immediate report.

Command parameters:

  • gpio : The number of the gpio to be configured (min=0, max=25)
  • value : Output value (i.e. 0 or 3.3 V) (min=0, max=1)
  • _callback : Optionally, a function to handle future report(s). If set, makes this command asynchronous so it does not wait for the command being finished.

Report returns:

  • report_code : 1 identifies command & report type

gpio_in

gpio_in(gpio,  _callback=None)

Returns the digital state of a gpio pin.

Typically used when the pin is set to high-z or pull-up/down.

Caution

The maximum allowed voltage at any pin is 3.3V.

This command results in single near-immediate report.

Command parameters:

  • gpio : (min=0, max=25)
  • _callback : Optionally, a function to handle future report(s). If set, makes this command asynchronous so it does not wait for the command being finished.

Report returns:

  • report_code : 2
  • gpio
  • value : 1 if pin connected to >2 V; 0 if connected to <1 V

gpio_on_change

gpio_on_change(gpio, on_rising_edge=1, on_falling_edge=1,  _callback=None)

Sets up a gpio to issue a report every time the gpio changes its state. This is sensitive to both external and internal events.

Fixme: in current firmware, edge events cannot be turned off!

This command potentially results in multiple later reports. Note that input signal of over 10-50kHz may result in some events not being reported.

Command parameters:

  • gpio : gpio specification (min=0, max=25)
  • on_rising_edge : Reports on gpio rising from logical 0 to 1 (min=0, max=1, default=1)
  • on_falling_edge : Reports on gpio falling from logical 1 to 0 (min=0, max=1, default=1)
  • _callback : Optionally, a function to handle future report(s). If set, makes this command asynchronous so it does not wait for the command being finished.

Report returns:

  • report_code : 3
  • gpio : The pin at which the event was detected.
  • events : The value of 4 corresponds to falling edge, 8 to rising edge.
  • time_us : Timestamp in microseconds.

gpio_highz

gpio_highz(gpio,  _callback=None)

Changes the output state of the specified gpio, i.e. general-purpose input/output pin.

The pin will become "high-impedance", or "floating", disconnected from any voltage supply or drain.

This overrides previous direct-output or pull-up/down state of the pin.

This command results in single, meaningless, near-immediate report.

Command parameters:

  • gpio : The number of the gpio to be configured (min=0, max=25)
  • _callback : Optionally, a function to handle future report(s). If set, makes this command asynchronous so it does not wait for the command being finished.

Report returns:

  • report_code : 4 identifies command & report type

gpio_pull

gpio_pull(gpio, value,  _callback=None)

Changes the output state of the specified gpio, i.e. general-purpose input/output pin.

Depending on the "pull=0" or "pull=1" parameter, it engages one of the built-in cca. 50 kOhm resistors to pull the pin towards 0 or 3.3 V, respectively.

This overrides previous direct-output or high-impedance state of the pin.

This command results in single, meaningless, near-immediate report.

Command parameters:

  • gpio : The number of the gpio to be configured (min=0, max=25)
  • value : Output value (i.e. 0 or 3.3 V), valid if not set to high-impedance mode. (min=0, max=1)
  • _callback : Optionally, a function to handle future report(s). If set, makes this command asynchronous so it does not wait for the command being finished.

Report returns:

  • report_code : 5 identifies command & report type

adc

adc(channel_mask=1, blocksize=1000, infinite=0, blocks_to_send=1, clkdiv=96, trigger_gpio=-1, trigger_on_falling_edge=0,  _callback=None)

Initiates analog-to-digital conversion (ADC), using the RP2040 built-in feature.

When ADC is already active, this takes no action. Use adc_stop() first in such a case.

This command can result in one, several or infinitely many report(s). They can be almost immediate or delayed, depending on block size and timing.

Command parameters:

  • channel_mask : Bits 0x01, 0x02, 0x04 are GPIO26, 27, 28; mask 0x08 internal reference, 0x10 temperature sensor (min=1, max=31, default=1)
  • blocksize : Number of sample points until a report is sent (min=1, max=8192, default=1000)
  • infinite : Disables blocks_to_send countdown; reports will keep coming until stopped by adc(blocks_to_send=0) (min=0, max=1, default=0)
  • blocks_to_send : Limits the number of reports to be sent (if the 'infinite' option is not set) (min=1, default=1)
  • clkdiv : Sampling rate is 48MHz/clkdiv (e.g. 96 gives 500 ksps; 48000 gives 1000 sps etc.) (min=96, max=65535, default=96)
  • trigger_gpio : GPIO number for start trigger (leave -1 to make ADC start immediately) (min=-1, max=24, default=-1)
  • trigger_on_falling_edge : If set to 1, triggers on falling edge instead of rising edge. (min=0, max=1, default=0)
  • _callback : Optionally, a function to handle future report(s). If set, makes this command asynchronous so it does not wait for the command being finished.

Report returns:

  • report_code : 6
  • data : as a list of integers.
  • start_time_us : Microsecond timestamp when ADC started this block acquisition.
  • end_time_us : Microsecond timestamp when ADC finished this block acquisition.
  • start_sync_value : Stepper[0] nanoposition when ADC started this block acquisition. (Will be configurable in future.)
  • end_sync_value : Stepper[0] nanoposition when ADC finished this block acquisition. (dtto)
  • channel_mask : The channel_mask value that was used (see adc() call parameters for details).
  • blocks_to_send : How many blocks remain to be sent. Does not change if adc set to infinite.
  • block_delayed_by_usb : Normally should be 0, except USB was overloaded and the ADC block had to wait for the USB buffer to accept new data.

adc_stop

adc_stop(finish_last_adc_packet=1,  _callback=None)

Manually sets the analog-to-digital conversion not to start another sampling ADC block after the active block is finished. Also an ADC block won't be started if it is waiting for a trigger event to start.

Still, one or more ADC report(s) may still arrive after adc_stop() being issued; these were either actively sampled at the moment, or were stored in the USB transmit queue.

Tip

Adc_stop() is most useful when adc(infinite=True) was previously called. Stopping ADC is also necessary to re-run it with different configuration. But if you want to sample exactly X blocks it may be easier to specify their number by calling adc(blocks_to_send=X) instead.

If ADC is not running, this takes no action.

This command will result in one immediate report.

Command parameters:

  • finish_last_adc_packet : (No option here - hard stopping of ADC in the middle of a block not implemented yet.) (min=1, max=1, default=1)
  • _callback : Optionally, a function to handle future report(s). If set, makes this command asynchronous so it does not wait for the command being finished.

Report returns:

  • report_code : 7
  • aborted_blocks_to_send

pwm_configure_pair

pwm_configure_pair(gpio=0, wrap_value=999, clkdiv=1, clkdiv_int_frac=0,  _callback=None)

Sets frequency for a "PWM slice", i.e. pair of GPIOs

To control usual small servos, set wrap_value=65535, clkdiv=20 to get 190 Hz cycle. Value of 10000 (0.8ms pulse) then turns servo near its minimum value, and value of 30000 (2.4ms pulse) turns it near maximum value. YMMV. (see https://en.wikipedia.org/wiki/Servo_control)

When PWM is low-pass filtered to generate analog signal (like a poor man's DAC), clkdiv=1 is recommended as it gives optimum duty-cycle resolution; the wrap value can be reduced to get faster cycle, thus more efficient filtering & better time resolution.

Note

Note while almost all GPIOs can be enabled for PWM output, there are only 16 channels (e.g. GPIOs 0, 16 will have the same value, if these are enabled for PWM output), and there are only 8 PWM slices. As a result, GPIOs 0, 1, 16 and 17 share also the same clkdiv, wrap and clkdiv_int_frac values. Changing them for one of these pins changes it for other, too.)

This command results in one near-immediate report.

Command parameters:

  • gpio : Selected pin for PWM output. Note not all pins are independent, see above. (min=0, max=25, default=0)
  • wrap_value : Value at which PWM counter resets for a new cycle. (min=1, max=65535, default=999)
  • clkdiv : Clock divider for PWM. (min=1, max=255, default=1)
  • clkdiv_int_frac : Fine tuning of the frequency by clock divider dithering. (min=0, max=15, default=0)
  • _callback : Optionally, a function to handle future report(s). If set, makes this command asynchronous so it does not wait for the command being finished.

Report returns:

  • report_code : 8

pwm_set_value

pwm_set_value(gpio=0, value=0,  _callback=None)

Quickly sets duty cycle for one GPIO

It is assumed this GPIO already was configured by pwm_configure_pair().

This command results in one near-immediate report.

Command parameters:

  • gpio : (min=0, max=25, default=0)
  • value : The counter value at which PWM pin switches from 1 to 0. For example, set value to wrap_value//2 (defined by pwm_configure_pair) to achieve a 50% duty cycle. (min=0, max=65535, default=0)
  • _callback : Optionally, a function to handle future report(s). If set, makes this command asynchronous so it does not wait for the command being finished.

Report returns:

  • report_code : 9

stepper_init

stepper_init(stepper_number, dir_gpio, step_gpio, endswitch_gpio=-1, disable_gpio=-1, inertia=30,  _callback=None)

Rp2daq allows to control up to 16 independent stepper motors, provided that each motor has its current driver compatible with Stepstick A4988. For this driver rp2daq generates two control signals - "dir" and "step" - determining the direction and speed of rotation, respectively. The GPIO numbers of these signals are mandatory parameters.

Caution

Never disconnect a stepper from Stepstick when powered. Interrupting the current in its coils results in a voltage spike that may burn the driver chip.

This command only defines constants and initializes the GPIO states, but does not move the stepper; see stepper_move() for getting it moving.

It results in one immediate report.

Command parameters:

  • stepper_number : The number of the stepper to be configured. (min=0, max=15)
  • dir_gpio : Direction-controlling output GPIO pin. (min=0, max=24)
  • step_gpio : Microstep-advancing output GPIO pin. (min=0, max=24)
  • endswitch_gpio : GPIO that, once shorted to ground, can automatically stop the stepper whenever it reaches the minimum (or maximum) allowed position. The end stop switch is both safety and convenience measure, allowing one to easily calibrate the stepper position upon restart. More details are with the stepper_move() command. (min=-1, max=24, default=-1)
  • disable_gpio : GPIO number that may be connected to the "!enable" pin on A4988 module - will automatically turn off current to save energy when the stepper is not moving. Note however it also loses its holding force. (min=-1, max=25, default=-1)
  • inertia : Allows for smooth acc-/deceleration of the stepper, preventing it from losing steps at startup even at high rotation speeds. The default value is usually OK unless the stepper moves some heavy mass. (min=0, max=10000, default=30)
  • _callback : Optionally, a function to handle future report(s). If set, makes this command asynchronous so it does not wait for the command being finished.

Report returns:

  • report_code : 10
  • initial_nanopos : This is the nanoposition the stepper was initialized to; always 0 in current firmware.

stepper_move

stepper_move(stepper_number, to, speed, endswitch_sensitive_up=0, endswitch_sensitive_down=1, relative=0, reset_nanopos_at_endswitch=0,  _callback=None)

Starts stepping motor movement from current position towards the new position given by "to". The motor has to be initialized by stepper_init first (please refer to this command for more details on stepper control).

Tip

The units of position are nanosteps, i.e., 1/256 of a microstep. So typically if you have a motor with 200 steps per turn and your A4988-compatible driver is hard-wired for 16 microsteps/step, it takes about a million (200x256x16 = 819200) nanosteps per turn.

The "speed" is in nanosteps per 0.1 ms update cycle; thus setting speed=82 turns the motor in the above example once in second. Setting minimal speed=1 gives 0.732 RPM. Note most stepper motors won't be able to turn much faster than 600 RPM.

Note: The defaults for the two endswitch-related options assume you installed the endswitch at the lowest end of the stepper range. Upon reaching the endswitch, the stepper position is typically calibrated and it is straightforward to move upwards from the endswitch, without any change to the defaults. Alternately, one can swap these two options if the endswitch is mounted on the highest end of the range. Or one can use different settings before/after the first calibration to allow the motor going beyond the end-switch(es) - if this is safe.

The initial and terminal part of the movement are smoothly ac-/de-celerated, however issuing this command to an already moving stepper results in its immediate stopping before it starts moving smoothly again.

Tip

As with all other commands taking some time to finish, moving a stepper blocks your program until the movement is finished. Using asychronous commands one can easily make multiple steppers move at once.

This command results in one report after the movement is finished. Thus it may be near immediate or delayed by seconds, minutes or hours, depending on the distance and speed.

Command parameters:

  • stepper_number : (min=0, max=15)
  • to
  • speed : (min=1, max=10000)
  • endswitch_sensitive_up : If unset, the motor will move towards more positive target positions independent of the end switch pin. (min=0, max=1, default=0)
  • endswitch_sensitive_down : If set, the motor will immediately stop its movement towards more negative target positions when the end switch pin gets connected to zero. (min=0, max=1, default=1)
  • relative : If set to 1, rp2daq will add the to value to current nanopos; movement then becomes relative to the position of the motor when the command is issued. (min=0, max=1, default=0)
  • reset_nanopos_at_endswitch : will reset the position if endswitch triggers the end of the movement. This is a convenience option for easy calibration of position using the endswitch. Note that the nanopos can also be manually reset by re-issuing the stepper_init() function. (min=0, max=1, default=0)
  • _callback : Optionally, a function to handle future report(s). If set, makes this command asynchronous so it does not wait for the command being finished.

Report returns:

  • report_code : 11
  • stepper_number
  • nanopos
  • endswitch_was_sensitive
  • endswitch_triggered
  • steppers_init_bitmask
  • steppers_moving_bitmask
  • steppers_endswitch_bitmask
  • start_time_us
  • end_time_us

stepper_status

stepper_status(stepper_number,  _callback=None)

Returns the position and endswitch status of the stepper selected by "stepper_number".

Additionally, returns three 16-bit integers (bitmasks) for all indices 0..15, describing if each corresponding stepper was initialized, if it is actively moving and if it is currently at endswitch.

These bitmasks are particularly useful when multiple steppers are to be synchronized, e.g., into a two-dimensional movement. (New set of stepper_move() commands then would be issued only when all relevant bits in steppers_moving_bitmask are cleared.)

This command results in one immediate report.

Command parameters:

  • stepper_number : (min=0, max=15)
  • _callback : Optionally, a function to handle future report(s). If set, makes this command asynchronous so it does not wait for the command being finished.

Report returns:

  • report_code : 12
  • timestamp_us
  • stepper_number
  • endswitch
  • nanopos
  • steppers_init_bitmask
  • steppers_moving_bitmask
  • steppers_endswitch_bitmask