{"id":21196111,"url":"https://github.com/ttitanua/micropython_servo_pdm_360","last_synced_at":"2025-07-10T05:30:24.491Z","repository":{"id":65947942,"uuid":"602681944","full_name":"TTitanUA/micropython_servo_pdm_360","owner":"TTitanUA","description":"This is a micropython library for control continuous servo by PDM (PWM).","archived":false,"fork":false,"pushed_at":"2023-10-30T15:52:41.000Z","size":54,"stargazers_count":13,"open_issues_count":0,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-26T02:48:50.325Z","etag":null,"topics":["mg995-360","micropython","raspberry-pi-pico","servo-360"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TTitanUA.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-02-16T18:12:38.000Z","updated_at":"2025-04-13T03:02:54.000Z","dependencies_parsed_at":null,"dependency_job_id":"9c3d2c94-cd81-4e2d-845c-217d57461a52","html_url":"https://github.com/TTitanUA/micropython_servo_pdm_360","commit_stats":{"total_commits":6,"total_committers":2,"mean_commits":3.0,"dds":"0.16666666666666663","last_synced_commit":"4e20c49b55745c33691f0e34c29d5af16eb60661"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/TTitanUA/micropython_servo_pdm_360","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TTitanUA%2Fmicropython_servo_pdm_360","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TTitanUA%2Fmicropython_servo_pdm_360/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TTitanUA%2Fmicropython_servo_pdm_360/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TTitanUA%2Fmicropython_servo_pdm_360/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TTitanUA","download_url":"https://codeload.github.com/TTitanUA/micropython_servo_pdm_360/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TTitanUA%2Fmicropython_servo_pdm_360/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264535988,"owners_count":23624404,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mg995-360","micropython","raspberry-pi-pico","servo-360"],"created_at":"2024-11-20T19:33:49.237Z","updated_at":"2025-07-10T05:30:24.220Z","avatar_url":"https://github.com/TTitanUA.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![pypi version shield](https://img.shields.io/pypi/v/micropython-servo-pdm-360)](https://pypi.org/project/micropython-servo-pdm-360/) \n[![pypi downloads per month shield](https://img.shields.io/pypi/dm/micropython-servo-pdm-360?color=brightgreen)](https://pypi.org/project/micropython-servo-pdm-360/)\n\nThis is an automatic translation, may be incorrect in some places.\n# Servo PDM Continuous\nA library for controlling continuous rotation servo drives via the PWM interface of the Raspberry Pi Pico microcontroller in MicroPython.\n\nLibrary features:\n- Rotation with a given force and direction\n- Rotation within the specified time\n- Possibility of soft start and stop\n- Ability to use the [smooth-servo](https://pypi.org/project/smooth-servo/) library to change the smooth start and stop algorithm\n- All pending work happens in the background, with two processing options:\n     - Using an asyncio task (recommended)\n     - Interrupt timer\n\nIf you don't need all the functionality listed above, then you should take a look at the [micropython-servo](https://pypi.org/project/micropython-servo/) library.\nIt is much smaller and better suited for simple tasks.\n\nThe following materials were used in the development of the library:\n- Material [Principle of operation of constant rotation servos](http://wiki.amperka.ru/articles:servo-pdm-continuous-rotation), author amperka.ru\n- Material [Servo Motor with Raspberry Pi Pico using MicroPython](https://microcontrollerslab.com/servo-motor-raspberry-pi-pico-micropython/) by microcontrollerslab.com\n- Material [Hobby Servo Tutorial](https://learn.sparkfun.com/tutorials/hobby-servo-tutorial?_ga=2.2724022.723022425.1676642363-1173110823.1674579241) by MIKEGRUSIN and BYRON J. (sparkfun.com)\n\n### Compatibility\n- MicroPython 1.19.1\n- Raspberry Pi Pico\n\nOn the hardware above the library has been tested and works correctly.\n\n### ATTENTION\nYou use this module at your own risk.\nI am new to MicroPython programming. So there may be nuances that I did not take into account.\nIf you notice an error or have suggestions for improvement, please write to Issues.\n\n## Content\n- [Installation](https://github.com/TTitanUA/micropython_servo_pdm_360#install)\n- [Initialization](https://github.com/TTitanUA/micropython_servo_pdm_360#init)\n- [Documentation](https://github.com/TTitanUA/micropython_servo_pdm_360#doc)\n- [Examples](https://github.com/TTitanUA/micropython_servo_pdm_360/tree/main/examples)\n- [Bugs and feedback](https://github.com/TTitanUA/micropython_servo_pdm_360#feedback)\n\n\u003ca name=\"install\"\u003e\u003c/a\u003e\n## Installation\n- Install the library via pip (Thonny -\u003e Manage Packages) by name **micropython-servo-pdm-360**\n- Or manual installation:\n   - [Download library from GitHub](https://github.com/TTitanUA/micropython_servo_pdm_360)\n   - take the **micropython_servo_pdm_360** folder from the archive.\n   - upload to the root of the microcontroller or to the **lib** folder.\n\nIf you want to play around with the logic of the library, then the 2nd installation option is preferable. :)\n\n\u003ca name=\"init\"\u003e\u003c/a\u003e\n## Initialization\n### Initializing the base library\n```python\nfrom machine import Pin, PWM\nfrom micropython_servo_pdm_360 import ServoPDM360\n\n# create a PWM servo controller (21 - pin Pico)\nservo_pwm = PWM(Pin(21))\n\n# Set the parameters of the servo pulses, more details in the \"Documentation\" section\nfreq = 50\nmin_us = 400\nmax_us = 2550\ndead_zone_us = 150\n\n# create a servo object\nservo = ServoPDM360(pwm=servo_pwm, min_us=min_us, max_us=max_us, dead_zone_us=dead_zone_us, freq=freq)\n```\n\nAfter that, [basic methods](https://github.com/TTitanUA/micropython_servo_pdm_360#doc_base) of controlling the servo will be available to you, which do not require pending tasks.\n\nTo access additional methods that require deferred execution, you need to initialize one of the child classes.\nDepending on which of the ways you prefer to handle pending tasks:\n\n#### Using the uasyncio library\nThis is the best option for most projects.\n```python\nfrom machine import Pin, PWM\nfrom micropython_servo_pdm_360 import ServoPDM360RP2Async\n\n# create a PWM servo controller (21 - pin Pico)\nservo_pwm = PWM(Pin(21))\n\n# Set the parameters of the servo pulses, more details in the \"Documentation\" section\nfreq = 50\nmin_us = 1350\nmax_us = 8450\ndead_zone_us = 300\n\n# create a servo object\nservo = ServoPDM360RP2Async(pwm=servo_pwm, min_us=min_us, max_us=max_us, dead_zone_us=dead_zone_us, freq=freq)\n```\n\n#### Using timer interrupts\nYou can read more about timers [here](https://docs.micropython.org/en/latest/library/machine.Timer.html)\nFor Raspberry Pi Pico [here](https://docs.micropython.org/en/latest/rp2/quickref.html#timers)\nBe careful, although this is the easiest option, it is not optimal.\nSince the handling of servo events occurs in a timer interrupt, other interrupts will be delayed.\n```python\nfrom machine import Pin, PWM\nfrom micropython_servo_pdm_360 import ServoPDM360RP2Irq\n\n# create a PWM servo controller (21 - pin Pico)\nservo_pwm = PWM(Pin(21))\n\n# Set the parameters of the servo pulses, more details in the \"Documentation\" section\nfreq = 50\nmin_us = 400\nmax_us = 2550\ndead_zone_us = 150\n\n# create a servo object\nservo = ServoPDM360RP2Irq(pwm=servo_pwm, min_us=min_us, max_us=max_us, dead_zone_us=dead_zone_us, freq=freq)\n```\n\n\u003ca id=\"doc\"\u003e\u003c/a\u003e\n## Documentation\n\u003ca id=\"doc_pdm\"\u003e\u003c/a\u003e\n### A little about PDM\nPDM(pulse-duration modulation) is a process of power control by pulsing the power consumer on and off. By Wikipedia®\nIn our case, it is used to control the servo. According to the pulse time, you can set the force and direction of rotation of the servo.\n**ATTENTION:** Unlike PWM, the control is not based on frequency, but on the duration of the pulse.\nYou can read more here (with pictures): [wiki.amperka.ru](http://wiki.amperka.ru/articles:servo-pdm-continuous-rotation#%D0%B8%D0%BD%D1%82%D0%B5%D1%80%D1%84%D0%B5%D0%B9%D1%81_%D1%83%D0%BF%D1%80%D0%B0%D0%B2%D0%BB%D0%B5%D0%BD%D0%B8%D1%8F)\n\nFor the correct operation of the servo, we need to set the following parameters:\n- **freq** - pulse frequency, for analog servos 50 Hz. For digital 300 Hz or more.\n- **min_us** - minimum pulse time at which the servo begins to rotate in one direction.\n- **max_us** - maximum pulse time at which the servo stops rotating in the other direction.\n- **dead_zone_us** - duration of the central zone in which the servo does not rotate. This is the transition zone between the two directions of rotation.\n\nBelow I tried to graphically represent these parameters for the MG995_360 analog servo:\n\n![pdm configure](pdm_configure.png)\n\nAs we can see in the figure, the servo begins to rotate at a pulse width of 400 µs, and stops rotating at 2600 µs.\nThus, we get the parameters `min_us=400` and `max_us=2550` (2600 - 50, since at 2600 the drive has already stopped). Now we need to find the duration of the central zone.\nThe figure shows that at a pulse length of 1450 µs, the servo stops rotating clockwise and stops.\nFurther, at a pulse length of 1600 μs, the rotation in the opposite direction begins. Thus the parameter `dead_zone_us=150` (1600-1450).\n\nWhere can I get these parameters for a specific servo? It all depends on the manufacturer. But in most cases they are specified in the documentation.\nIf not, we pick them up manually using the `set_duty` method and giving different values from 0 to 3000 µs, in 50 µs increments.\nAn example of such a configuration can be found in the examples folder file [manual_config.py](https://github.com/TTitanUA/micropython_servo_pdm_360/tree/main/examples/manual_config.py).\n\n#### List of parameters for servos:\n- **MG995_360** - `min_us=400`, `max_us=2550`, `dead_zone_us=150`, `freq=50`\n- **[Com-Motor05(joy it FS90R)](https://joy-it.net/en/products/COM-Motor05)** - `min_us=700`, `max_us=2300`, `dead_zone_us=90`, `freq=50` - By [@philsuess](https://github.com/philsuess)\n\n**PLEASE:** If you find parameters for a servo that are not listed, submit them to me via [issue](https://github.com/TTitanUA/micropython_servo_pdm_360/issues).\n\n### ServoPDM360 constructor parameters\n**ServoPDM360RP2Async** and **ServoPDM360RP2Irq** inherit it and have the same parameters\n\n| Parameter    | Type | Default | Description                  |\n|--------------|------|---------|------------------------------|\n| pwm          | PWM  | None    | PWM controller               |\n| min_us       | int  | 500     | Minimum impulse time         |\n| max_us       | int  | 3000    | Maximum pulse time           |\n| dead_zone_us | int  | 150     | Duration of the central zone |\n| freq         | int  | 50      | Pulse frequency              |\n| invert       | bool | false   | Direction inversion          |\n\n- `pwm` - [PWM](https://docs.micropython.org/en/latest/library/machine.PWM.html) controller object.\n- `min_us` - Minimum pulse time (duty cycle) [More](https://github.com/TTitanUA/micropython_servo_pdm_360#doc_pdm).\n- `max_us` - Maximum pulse time (duty cycle) [More](https://github.com/TTitanUA/micropython_servo_pdm_360#doc_pdm)\n- `dead_zone_us` - Central zone duration [More](https://github.com/TTitanUA/micropython_servo_pdm_360#doc_pdm)\n- `freq` - Pulse frequency, for analog drives it is 50. Digital drives are usually 300 or more.\n- `invert` - Invert direction (maybe needed for some drives, maybe not :) )\n\n\u003ca id=\"doc_base\"\u003e\u003c/a\u003e\n### ServoPDM360 base class methods\n- `set_duty(duty: int)` - Sets an arbitrary value of the duty cycle in the range from 0 to 65000.\nThis method is intended for manual search of the minimum and maximum duty cycle values. [More](https://github.com/TTitanUA/micropython_servo_pdm_360#doc_pdm)\n- `turn_cv(force: int)` - Starts rotation of the drive clockwise with the given acceleration.\n- `turn_ccv(force: int)` - Starts the drive turning counterclockwise at the given acceleration.\n- `stop()` - Stops the rotation of the drive.\n- `deinit()` - Disables the PWM generator.\n\n### ServoPDM360RP2Async and ServoPDM360RP2Irq class methods\n- `turn_cv_ms(...)` - Rotates the drive clockwise with various parameters.\n- `turn_ccv_ms(...)` - Rotates the drive counterclockwise with various parameters.\n\n| Parameter       | Type            | Default | Description                                                                                              |\n|-----------------|-----------------|---------|----------------------------------------------------------------------------------------------------------|\n| time_ms         | int             | 0       | Rotation Time (0 - Infinite)                                                                             |\n| force           | int             | None    | Effort, if not specified, is taken from `start_smoothing`                                                |\n| start_smoothing | ServoSmoothBase | None    | Start deceleration, if the start is not specified, it will be instantaneous                              |\n| end_smoothing   | ServoSmoothBase | None    | Decelerate stop, if not specified stop will be instant                                                   |\n| callback        | callable        | None    | The function that will be called after the end of the command. If `time_ms` == 0 then after overclocking |\n\n- `smooth` - Smooth stop of the drive.\n\n| Parameter     | Type            | Default | Description                                                    |\n|---------------|-----------------|---------|----------------------------------------------------------------|\n| end_smoothing | ServoSmoothBase | None    | Stop slowdown                                                  |\n| callback      | callable        | None    | The function that will be called after the end of the command. |\n\n### Slowdowns\nTo control slowdowns, you can use the `ServoSmoothBase` classes and its descendants.\nThis library only has `SmoothLinear` linear deceleration, if you need more, install the [smooth-servo](https://pypi.org/project/smooth-servo/) library.\nAn example of using built-in easing:\n```python\nfrom machine import Pin, PWM\nfrom micropython_servo_pdm_360 import ServoPDM360RP2Async, SmoothLinear\n\n# create a PWM servo controller (21 - pin Pico)\nservo_pwm = PWM(Pin(21))\n\n# Set the parameters of the servo pulses, more details in the \"Documentation\" section\nfreq = 50\nmin_us = 400\nmax_us = 2550\ndead_zone_us = 150\n\n# create a servo object\nservo = ServoPDM360RP2Async(pwm=servo_pwm, min_us=min_us, max_us=max_us, dead_zone_us=dead_zone_us, freq=freq)\n\n# Rotate the actuator clockwise for two seconds with a force of 50 and decelerate at the beginning. After output to the console \"callback cv\"\nservo.turn_cv_ms(2000, 50, start_smoothing=SmoothLinear(50, 1000),  callback=lambda: print(\"callback cv\"))\n```\nDetails about the parameters and types of slowdowns can be found in the [smooth_servo documentation](https://github.com/TTitanUA/smooth_servo#doc).\n\n## Examples\nUsage examples can be found in the [examples](https://github.com/TTitanUA/micropython_servo_pdm_360/tree/main/examples)  folder.\n\n\u003ca id=\"feedback\"\u003e\u003c/a\u003e\n## Bugs and feedback\nIf you find bugs, create [issue](https://github.com/TTitanUA/micropython_servo_pdm_360/issues)\nThe library is open for further development and your [pull requests](https://github.com/TTitanUA/micropython_servo_pdm_360/pulls)!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fttitanua%2Fmicropython_servo_pdm_360","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fttitanua%2Fmicropython_servo_pdm_360","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fttitanua%2Fmicropython_servo_pdm_360/lists"}