Add functionality to set the Real-Time Playback value

[kriswilk]

This PR adds the ability to set the output value in Real-Time Playback mode. A port of this function from the DRV2605(L) Arduino library.

Closes #33

[jposada202020]

Hello :) first, thank you for the add!!. Hopefully, I would be able to test over the weekend. However, in the meantime, just one comment. As you would need to put the device in RTP mode before using this function, I think it would be a good idea to document it either in the documentation and/or with an example, maybe something equivalent to this?

Adafruit_CircuitPython_DRV2605/adafruit_drv2605.py

Lines 201 to 209 in 2200f21

	.. code-block:: python
	# Getting the effect stored in a slot
	slot_0_effect = drv.sequence[0]
	# Setting an Effect in the first sequence slot
	drv.sequence[0] = Effect(88)
	"""
	return self._sequence

Also, it would be good to create it as a property, so users could do something like
real_time_value = xxxxx

Let me know thanks :)

[kriswilk]

Thanks for the input. Both are good suggestions. I reworked the PR accordingly.

One change that may need explanation is allowing input values from -127 to 255. I did so since:

• by default, the device treats the register value as a signed 8-bit integer (-127 to 127).
• if the user sets the internal DATA_FORMAT_RTP bit to 1, the device treats the register value as unsigned (0 to 255)

Oddness occurs if the user READS a value outside 0-127 since the register is always read as unsigned. Without complicating the reading routine by also reading and checking the DATA_FORMAT_RTP bit, I don't see a way around this. I don't know if the overhead is worth it.

[jposada202020]

Thanks for the changes. I agree with you, it is indeed difficult to take into account all the corner cases, I think we are covering the default behaviour, verifying the value. and the note do a good job both explaining and refering to the datasheet for more information. will test probably probably later, just want to test the change on hardware :)

[jposada202020]

LGTM Thanks 👍🏼

Test

tested with Adafruit CircuitPython 8.0.2 on 2023-02-14; Adafruit Feather RP2040 with rp2040
and the following test script

import time
import board
import adafruit_drv2605


# Initialize I2C bus and DRV2605 module.
i2c = board.I2C()
drv = adafruit_drv2605.DRV2605(i2c)

print("Start real-time playback")
print("Mode value before:", drv.mode)
print("real time value before:", drv.realtime_value)
drv.realtime_value = 0
print("real time value after:", drv.realtime_value)
drv.mode = adafruit_drv2605.MODE_REALTIME
print("Mode value after:", drv.mode)

print("Buzz the motor briefly at 50% and 100% amplitude")
print("real time value before:", drv.realtime_value)
drv.realtime_value = 64
print("real time value after:", drv.realtime_value)
time.sleep(0.5)
print("real time value before:", drv.realtime_value)
drv.realtime_value = 127
print("real time value after:", drv.realtime_value)
time.sleep(0.5)

print("Stop real-time playback")
drv.realtime_value = 0
print("Mode value before:", drv.mode)
drv.mode = adafruit_drv2605.MODE_INTTRIG
print("Mode value after:", drv.mode)

Results

Start real-time playback
Mode value before: 0
real time value before: 0
real time value after: 0
Mode value after: 5
Buzz the motor briefly at 50% and 100% amplitude
real time value before: 0
real time value after: 64
real time value before: 64
real time value after: 127
Stop real-time playback
Mode value before: 5
Mode value after: 0