| Name | pymikro JSON |
| Version |
0.1.1
JSON |
| download |
| home_page | None |
| Summary | API to control the Maschine Mikro MK3 |
| upload_time | 2024-12-02 20:08:21 |
| maintainer | None |
| docs_url | None |
| author | flokapi |
| requires_python | <4.0,>=3.7 |
| license | LGPL-3.0-only |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Pymikro
Python module to control the Maschine Mikro MK3. It allows you to use this
maschine not only to create music, but also to control a home automation or a
robot or any other creative stuff.
It uses directly the USB HID protocol, as a result there is no dependency on a
product specific driver and it can run on any operating system. Furthermore,
this gives you access to the full capabilities of this hardware which makes it
even more fun to use.
## Usage
```python
import pymikro
maschine = pymikro.MaschineMikroMk3()
# control LEDs
lState = {
'button': {
'stop': {'val': 1}
},
'strip': {
1: {'val': 3, 'color': 'blue'}
},
'pad': {
1: {'val': 3, 'color': 'purple'}
}
}
maschine.lights.set_all(lState)
maschine.lights.set('pad', 6, 3, 'orange')
maschine.lights.set('strip', 5, 3, 'green')
maschine.lights.set('button', 'notes', 4)
maschine.lights.update()
# control screen
maschine.screen.set("Hello World!\nIt's working")
# get button and pad updates
while True:
cmd = maschine.read_cmd()
if cmd:
if cmd['cmd'] == 'pad':
print('Pad number {} pressed: {}'.format(cmd['pad_nb'], cmd['pad_val']))
if cmd['cmd'] == 'btn':
print('Buttons pressed: {}'.format(cmd['btn_pressed']))
```
## Setup
### Linux
Install the hid driver
```bash
sudo apt-get install libhidapi-hidraw0
```
Install the package
```bash
pip3 install pymikro
```
Set permissions for the device
```bash
cd /tmp
wget https://raw.githubusercontent.com/flokapi/pymikro/main/50-ni-maschine.rules
sudo cp 50-ni-maschine.rules /etc/udev/rules.d/
```
Plug or re-plug the maschine mikro USB cable.
### Windows
Install the hid driver:
1. Donwload the latest version of `hidapi-win.zip` from
<https://github.com/libusb/hidapi/releases>
2. Extract the zip file and copy the `hidapi.dll` corresponding to your
architecture to `C:\Users\<Username>\AppData\Local\Programs\Python`
Install the package
```bash
pip3 install pymikro
```
Plug or re-plug the maschine mikro USB cable.
## About
### Supported hardware features
Overall, there is actually more feature than the manufacturer uses :)
Pads:
- Set color (17 possible values) and intensity
- Get pressure value
- Info whether pressed, touched, or released
Buttons:
- get buttons being pressed
- set light brightness
Encoder:
- get value of the encoder (1 byte), and how much it moved
- whether it's being touched (not pressed)
Touch strip:
- get position of up to 2 fingers
- set color and brightness of each LED
Screen:
- set text with adjustable size, on 1 or 2 lines
### Supported operating systems
Tested on Linux & Windows
Should also work on OSX by installing the hid api. See
<https://pypi.org/project/hid/>
### API
#### Connection
```python
import pymikro
maschine = pymikro.MaschineMikroMk3()
maschine.hid.show_info()
```
#### Inputs
LEDs:
- The state of the LEDs for the pads/touch strip/buttons is defined in a single
data-structure which can be accessed and modified using the `lights.get_all`
and `lights.set_all` methods. The LEDs can also be set individually using
`lights.set`.
- To apply the changes, `lights.update` must be called. Using a separate command
allows to apply all the changes in a single write procedure (about 15ms) and
increases the reactivity.
- Example:
```python
maschine.lights.set_all({}) # set empty dictionary to disable all LEDs
maschine.lights.update()
time.sleep(1)
lState = {
'button': {
'stop': {'val': 1} # Button brighness value must be between 0
},
'strip': {
1: {'val': 4, 'color': 'blue'} # Touch Strip LED brightness value must be between 0 and 3
},
'pad': {
1: {'val': 3, 'color': 'purple'} # Pad brightness value must be between 0 and 3
}
}
maschine.lights.set_all(lState)
maschine.lights.set('pad', 6, 3, 'orange') # pad nb 6, brightness 3.
maschine.lights.set('strip', 5, 3, 'green') # strip led nb 5, brightness 3.
maschine.lights.set('button', 'notes', 4) # button 'notes', brightness 4.
maschine.lights.update()
```
Screen
- Example
```python
maschine.screen.set("Hello", 24) # Font size set to 24
maschine.screen.set(f"Hello World!\nIt's working") # Printing text on both lines with '\n'.
# Default font size is 14
```
#### Outputs
Output commands can be read in a non-blocking way using the `read_cmd` method,
which returns:
- `None` if no new command is available
- A dictionary which content differs depending on the `cmd` key value (`btn` or
`pad`)
- Example: `cmd = maschine.read_cmd()`
Pads
- The pad command is only sent when the state of a pad is being changed
(pressed/touched/released). The pad command is sent for a single pad at the
time.
- Example
```python
{
'cmd': 'pad',
'pad_nb': 5,
'pad_val': 1360, # between 0 and 4095
'touched': True, # finger in contact with the pad
'pressed': False, # finger just pressed the pad (not 100% reliable)
'released': False # finger just released the pad (not 100% reliable)
}
```
Buttons:
- The button command is only sent when the state of the buttons/touch
strip/encoder changed (including button release). The command contains the
full state of the button group.
- Example
```python
{
'cmd': 'btn',
'btn_pressed': ['group', 'pattern', 'enter'], # currently pressed buttons
'encoder_pos': 10, # byte, cyclic value between 0 and 15
'encoder_move': 1, # encoded moved to the right (+1) or left (-1)
'encoder_touched': True, # finger in contact with the encoder
'strip_pos_1': 123, # value of the strip if one finger touching
'strip_pos_2': 0 # second value if another finger is on the strip
}
```
### Alternatives
[maschine-mikro-mk3-driver](https://github.com/r00tman/maschine-mikro-mk3-driver)
- Built for Linux only
- Makes the Maschine Mikro available through a midi interface
- Coded in Rust
Midi mode
- Windows/OSX only (midi interface emulated by the driver)
- press `shift` and `project` to enter midi mode
- you can use [mido](https://pypi.org/project/mido/) or any other software to
handle the midi commands
- limited features/customization
Raw data
{
"_id": null,
"home_page": null,
"name": "pymikro",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.7",
"maintainer_email": null,
"keywords": null,
"author": "flokapi",
"author_email": "flokapi@pm.me",
"download_url": "https://files.pythonhosted.org/packages/29/5e/7d85ed0ddba0121f10ae1d7d4a1de86ac65dc01a1ab2abe76631a4e1b371/pymikro-0.1.1.tar.gz",
"platform": null,
"description": "# Pymikro\n\nPython module to control the Maschine Mikro MK3. It allows you to use this\nmaschine not only to create music, but also to control a home automation or a\nrobot or any other creative stuff.\n\nIt uses directly the USB HID protocol, as a result there is no dependency on a\nproduct specific driver and it can run on any operating system. Furthermore,\nthis gives you access to the full capabilities of this hardware which makes it\neven more fun to use.\n\n## Usage\n\n```python\nimport pymikro\n\nmaschine = pymikro.MaschineMikroMk3()\n\n# control LEDs\nlState = {\n 'button': {\n 'stop': {'val': 1}\n },\n 'strip': {\n 1: {'val': 3, 'color': 'blue'}\n },\n 'pad': {\n 1: {'val': 3, 'color': 'purple'}\n }\n}\nmaschine.lights.set_all(lState)\n\nmaschine.lights.set('pad', 6, 3, 'orange')\nmaschine.lights.set('strip', 5, 3, 'green')\nmaschine.lights.set('button', 'notes', 4)\nmaschine.lights.update()\n\n# control screen\nmaschine.screen.set(\"Hello World!\\nIt's working\")\n\n# get button and pad updates\nwhile True:\n cmd = maschine.read_cmd()\n if cmd:\n if cmd['cmd'] == 'pad':\n print('Pad number {} pressed: {}'.format(cmd['pad_nb'], cmd['pad_val']))\n if cmd['cmd'] == 'btn':\n print('Buttons pressed: {}'.format(cmd['btn_pressed']))\n```\n\n## Setup\n\n### Linux\n\nInstall the hid driver\n\n```bash\nsudo apt-get install libhidapi-hidraw0\n```\n\nInstall the package\n\n```bash\npip3 install pymikro\n```\n\nSet permissions for the device\n\n```bash\ncd /tmp\nwget https://raw.githubusercontent.com/flokapi/pymikro/main/50-ni-maschine.rules\nsudo cp 50-ni-maschine.rules /etc/udev/rules.d/\n```\n\nPlug or re-plug the maschine mikro USB cable.\n\n### Windows\n\nInstall the hid driver:\n\n1. Donwload the latest version of `hidapi-win.zip` from\n <https://github.com/libusb/hidapi/releases>\n\n2. Extract the zip file and copy the `hidapi.dll` corresponding to your\n architecture to `C:\\Users\\<Username>\\AppData\\Local\\Programs\\Python`\n\nInstall the package\n\n```bash\npip3 install pymikro\n```\n\nPlug or re-plug the maschine mikro USB cable.\n\n## About\n\n### Supported hardware features\n\nOverall, there is actually more feature than the manufacturer uses :)\n\nPads:\n\n- Set color (17 possible values) and intensity\n- Get pressure value\n- Info whether pressed, touched, or released\n\nButtons:\n\n- get buttons being pressed\n- set light brightness\n\nEncoder:\n\n- get value of the encoder (1 byte), and how much it moved\n- whether it's being touched (not pressed)\n\nTouch strip:\n\n- get position of up to 2 fingers\n- set color and brightness of each LED\n\nScreen:\n\n- set text with adjustable size, on 1 or 2 lines\n\n### Supported operating systems\n\nTested on Linux & Windows\n\nShould also work on OSX by installing the hid api. See\n<https://pypi.org/project/hid/>\n\n### API\n\n#### Connection\n\n```python\nimport pymikro\n\nmaschine = pymikro.MaschineMikroMk3()\nmaschine.hid.show_info()\n```\n\n#### Inputs\n\nLEDs:\n\n- The state of the LEDs for the pads/touch strip/buttons is defined in a single\n data-structure which can be accessed and modified using the `lights.get_all`\n and `lights.set_all` methods. The LEDs can also be set individually using\n `lights.set`.\n\n- To apply the changes, `lights.update` must be called. Using a separate command\n allows to apply all the changes in a single write procedure (about 15ms) and\n increases the reactivity.\n\n- Example:\n\n ```python\n maschine.lights.set_all({}) # set empty dictionary to disable all LEDs\n maschine.lights.update()\n\n time.sleep(1)\n\n lState = {\n 'button': {\n 'stop': {'val': 1} # Button brighness value must be between 0\n },\n 'strip': {\n 1: {'val': 4, 'color': 'blue'} # Touch Strip LED brightness value must be between 0 and 3\n },\n 'pad': {\n 1: {'val': 3, 'color': 'purple'} # Pad brightness value must be between 0 and 3\n }\n }\n maschine.lights.set_all(lState)\n\n maschine.lights.set('pad', 6, 3, 'orange') # pad nb 6, brightness 3.\n maschine.lights.set('strip', 5, 3, 'green') # strip led nb 5, brightness 3.\n maschine.lights.set('button', 'notes', 4) # button 'notes', brightness 4.\n maschine.lights.update()\n ```\n\nScreen\n\n- Example\n\n ```python\n maschine.screen.set(\"Hello\", 24) # Font size set to 24\n\n maschine.screen.set(f\"Hello World!\\nIt's working\") # Printing text on both lines with '\\n'.\n # Default font size is 14\n ```\n\n#### Outputs\n\nOutput commands can be read in a non-blocking way using the `read_cmd` method,\nwhich returns:\n\n- `None` if no new command is available\n- A dictionary which content differs depending on the `cmd` key value (`btn` or\n `pad`)\n- Example: `cmd = maschine.read_cmd()`\n\nPads\n\n- The pad command is only sent when the state of a pad is being changed\n (pressed/touched/released). The pad command is sent for a single pad at the\n time.\n\n- Example\n\n ```python\n {\n 'cmd': 'pad',\n 'pad_nb': 5,\n 'pad_val': 1360, # between 0 and 4095\n 'touched': True, # finger in contact with the pad\n 'pressed': False, # finger just pressed the pad (not 100% reliable)\n 'released': False # finger just released the pad (not 100% reliable)\n }\n ```\n\nButtons:\n\n- The button command is only sent when the state of the buttons/touch\n strip/encoder changed (including button release). The command contains the\n full state of the button group.\n\n- Example\n\n ```python\n {\n 'cmd': 'btn',\n 'btn_pressed': ['group', 'pattern', 'enter'], # currently pressed buttons\n 'encoder_pos': 10, # byte, cyclic value between 0 and 15\n 'encoder_move': 1, # encoded moved to the right (+1) or left (-1)\n 'encoder_touched': True, # finger in contact with the encoder\n 'strip_pos_1': 123, # value of the strip if one finger touching\n 'strip_pos_2': 0 # second value if another finger is on the strip\n }\n ```\n\n### Alternatives\n\n[maschine-mikro-mk3-driver](https://github.com/r00tman/maschine-mikro-mk3-driver)\n\n- Built for Linux only\n- Makes the Maschine Mikro available through a midi interface\n- Coded in Rust\n\nMidi mode\n\n- Windows/OSX only (midi interface emulated by the driver)\n\n- press `shift` and `project` to enter midi mode\n- you can use [mido](https://pypi.org/project/mido/) or any other software to\n handle the midi commands\n- limited features/customization\n\n",
"bugtrack_url": null,
"license": "LGPL-3.0-only",
"summary": "API to control the Maschine Mikro MK3",
"version": "0.1.1",
"project_urls": {
"documentation": "https://github.com/flokapi/pymikro",
"homepage": "https://github.com/flokapi/pymikro",
"repository": "https://github.com/flokapi/pymikro"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7fdb3dd1d5050269b06e5695a56d6eb1765295b5fcf83339c05e1350ae8d8c0d",
"md5": "ff34c06c76856015bfdbe5c5870d8f0d",
"sha256": "391836e690881cd4663a753a092cce317f7dbfc8e08273a154ff6759bd2b17ef"
},
"downloads": -1,
"filename": "pymikro-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ff34c06c76856015bfdbe5c5870d8f0d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.7",
"size": 397379,
"upload_time": "2024-12-02T20:08:18",
"upload_time_iso_8601": "2024-12-02T20:08:18.167581Z",
"url": "https://files.pythonhosted.org/packages/7f/db/3dd1d5050269b06e5695a56d6eb1765295b5fcf83339c05e1350ae8d8c0d/pymikro-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "295e7d85ed0ddba0121f10ae1d7d4a1de86ac65dc01a1ab2abe76631a4e1b371",
"md5": "c340038ba1a6c29d2a6e1c2a554f7aa9",
"sha256": "3312a4ddf29b1d8f938b5338861ac1fe5b6f24d966a9c46b85eb2870dc258f1e"
},
"downloads": -1,
"filename": "pymikro-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "c340038ba1a6c29d2a6e1c2a554f7aa9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.7",
"size": 399408,
"upload_time": "2024-12-02T20:08:21",
"upload_time_iso_8601": "2024-12-02T20:08:21.126670Z",
"url": "https://files.pythonhosted.org/packages/29/5e/7d85ed0ddba0121f10ae1d7d4a1de86ac65dc01a1ab2abe76631a4e1b371/pymikro-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-02 20:08:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "flokapi",
"github_project": "pymikro",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pymikro"
}
