You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+64-23Lines changed: 64 additions & 23 deletions
Original file line number
Diff line number
Diff line change
@@ -6,12 +6,14 @@ Animate your robot or animatronic project and take advantage of Blender's animat
6
6
7
7
Also check out the [Blender Servo Animation Arduino Library](https://github.com/timhendriks93/blender-servo-animation-arduino) which is specifically designed to work with this add-on.
- Send position values via a serial connection in real-time
16
+
- Send position values via a live mode connection in real-time
15
17
- Supporting Inverse Kinematics (IK)
16
18
17
19
## Installation
@@ -31,18 +33,16 @@ After enabling this Add-on, you should see a `Servo Settings` panel within the `
31
33
32
34
The underlying principle is that each bone represents a servo motor in the real world. To treat a bone as a servo and activate the `Servo Settings`, enable the checkbox in the panel header.
| Servo ID | Unique number between `0` and `255` to identify this servo (used to send serial commands) |
42
+
| Servo ID | Unique number between `0` and `255` to identify this servo (used to send live commands) |
41
43
| Position Min | The minimum position value to identify this servo physically stops moving |
42
44
| Position Max | Same as `Position Min`, but for the maximum value |
43
-
| Set Position Limits | Define a position range to limit the calculated position values according to a specific build |
44
-
| Position Limit Start | The minimum position value before the servo is supposed to stop moving within a specific build |
45
-
| Position Limit End | Same as `Position Limit Start`, but for the end value |
45
+
| Threshold | The maximum value change between frames which is also used for frame jump handling in live mode |
46
46
| Neutral Angle | The assumed neutral angle of the servo in degrees (typically half the rotation range) which should be adjusted carefully, since the servo will first move to its 'natural' neutral angle when powered |
47
47
| Rotation Range | The manufactured rotation range of the servo in degrees (typically `180`) |
48
48
| Euler Rotation Axis | The Euler rotation axis (`X`, `Y` or `Z`) of the bone rotation representing the servo movement |
@@ -59,9 +59,7 @@ It is also possible to use a different kind of value range. For example, to use
59
59
60
60
### Limiting the value range
61
61
62
-
The possible range of motion of a servo can be influenced by the specific design of your build. In this case, you can measure and use the position limit values to avoid damage to your setup.
63
-
64
-
You can also take advantage of Blender's functionality and use [bone constraints](https://docs.blender.org/manual/en/latest/animation/constraints/transform/limit_rotation.html) to already limit the bone rotation according to your build. The more precise your 3D model, the easier it will be to apply constraints and get an accurate preview of the real-world setup.
62
+
You can take advantage of Blender's functionality and use [bone constraints](https://docs.blender.org/manual/en/latest/animation/constraints/transform/limit_rotation.html) to already limit the bone rotation according to your build. The more precise your 3D model, the easier it will be to apply constraints and get an accurate preview of the real-world setup.
65
63
66
64
## Animating the Armature
67
65
@@ -75,7 +73,7 @@ Once all servo settings are provided and your animation is ready, you can calcul
75
73
76
74
Make sure to select the armature containing the bones/servos you want to export and choose the desired format in the `File > Export` menu:
Alternatively, you can also trigger the export via the timeline menu which is shown in the live mode section below.
81
79
@@ -92,33 +90,76 @@ For projects which involve an Arduino compatible microcontroller, the easiest wa
92
90
93
91
Apart from using the library, it is also possible to write use the exported data in any other kind of program. Especially the JSON format simply represents a list of position values which can be easily parsed via code.
94
92
95
-
## Live Mode via Serial Connection
93
+
## Live Mode
94
+
95
+
To make the animation process even more intuitive, you can enable the `Live mode` to send position commands via one of the following connection types:
96
+
97
+
- Serial (UART/USB)
98
+
- Web socket (TCP)
99
+
100
+
This will allow you to control your servos in real-time from within Blender.
101
+
102
+
### Installing dependencies
103
+
104
+
After enabling the add-on, you can find the `Servo Positions` popover menu in the header of the timeline. Before using the live mode feature of this add-on, you might have to install some Python dependencies first by pressing the `Install dependencies` button. This will automatically install the required `pip` packages and requires an active internet connection. This process can might take a few seconds depending on the speed of your internet connection.
96
105
97
-
To make the animation process even more intuitive, you can enable the `Live mode` to send position commands via a serial connection (UART/USB). This will allow you to control your servos in real-time from within Blender.
After enabling the add-on, you can find the `Servo Positions` popover menu in the header of the timeline. Here you can prepare and control the serial connection for the `Live mode`. For additional convenience, you can also find buttons to export the servo positions here.
108
+
Afterwards you can prepare and control the connection to be used for the `Live mode` via this menu. For additional convenience, you will also find buttons to export the servo positions here.
100
109
101
-
110
+
### Setup a connection
102
111
103
-
### Setup a Serial Connection
112
+
To use the `Live Mode`, you will need to prepare a receiver which will interpret the received commands and use them to control the servo motors accordingly.
104
113
105
-
To use the `Live Mode`, you will need to prepare a receiver which will interpret the received commands and use them to control the servo motors accordingly. In most cases, the receiver can be considered an Arduino compatible micro controller which is connected via USB to your PC.
114
+
In most cases, the receiver can be considered an Arduino compatible micro controller. As a first step, a connection method should be selected via the `Method` dropdown menu.
106
115
107
-
Once the micro controller is connected, the add-on will try to find and list the respective `Serial Port`. If there are multiple ports and you are unsure which one belongs to your controller, simply compare the list of ports after removing and re-connecting the device.
116
+
117
+
118
+
> Note: starting the `Live Mode` will immediately send the position values for all servos based on the current frame. Make sure that this will not break anything, as the servos will try to move to their new position as fast as possible.
119
+
120
+
#### Serial connection
121
+
122
+
Once the micro controller is connected via USB to your PC, the add-on will try to find and list the respective `Serial Port`. If there are multiple ports and you are unsure which one belongs to your controller, simply compare the list of ports after removing and re-connecting the device.
108
123
109
124
The `Baud Rate` specifies at which rate or speed the data will be transferred. It might need to be adjusted according to the limitations and configurations of your receiver. Keep in mind that a high frame rate combined with a multitude of servos requires a faster data transmission to achieve a smooth movement. As a reference, it was possible to smoothly control `16 servos` at `60 fps` with a baud rate of `115200`.
110
125
111
126
Once the `Serial Port` and `Baud Rate` have been set, you can click the `Connect` button to establish the serial connection and start the `Live Mode`.
112
127
113
-
> Note: starting the `Live Mode` will immediately send the position values for all servos based on the current frame. Make sure that this will not break anything, as the servos will try to move to their new position as fast as possible.
128
+
#### Web socket connection
129
+
130
+
It is also possible to send the position values via a TCP-based web socket connection. For example, one could use a WiFi-capable micro controller like the `ESP32` and set up a server to receive commands from Blender. The server should be in the same network as the machine which is running Blender.
131
+
132
+
After starting such a server, we can enter the respective IP address and port into the `Host` and `Port` input fields.
133
+
134
+
Clicking the `Connect` button will then establish a tcp connection and start the `Live Mode`.
114
135
115
136
### Position Jump Handling
116
137
117
-
Once the connection is established, you can use the timeline to control your servos in a synchronized way. This opens up the possibility to jump to a different frame or position within your animation. To prevent damage due to the servos moving too quickly, you can use `Position Jump Handling` and define a respective `Threshold`. This option is enabled by default.
138
+
Once the connection is established, you can use the timeline to control your servos in a synchronized way. This opens up the possibility to jump to a different frame or position within your animation. To prevent damage due to the servos moving too quickly, you can use `Position Jump Handling`. This option is enabled by default.
139
+
140
+
When clicking somewhere in the timeline and therefore jumping to a different frame, the add-on will first calculate all position value differences. If one of those differences exceeds the `Threshold` value of the respective servos, they will be slowly moved to their new target position. This is done by sending multiple position values in small increments. During this process, the user interface will show a progress indicator.
141
+
142
+
The speed of this process is also relative to the configured `Threshold` values. A slower and safer movement can be achieved by setting the threshold values as low as possible with the actual animation still able to run properly.
143
+
144
+
### Servo Calibration
145
+
146
+
While having an active live mode connection, it is possible to use a servo calibration feature. This will allow you to find the minimum and maximum position value of a servo similar to what you would normally do with a servo tester.
147
+
148
+
The calibration process can be started by clicking the `Calibrate servo` button within the servo settings panel:
> Note: the button will only be clickable when there is an active live mode connection.
153
+
154
+
Clicking this button will bring up a dialog containing a drop down menu to switch between the minimum and maximum position. You can then carefully adjust the position value until the servo stops moving. After doing so for both directions or position types, you can click on `OK` to apply these values as the new min and max position values.
> Note: Be careful when changing the position value and toggling the position type as the servo will move at full speed and position jump handling is not being considered.
118
159
119
-
When clicking somewhere in the timeline and therefore jumping to a different frame, the add-on will first calculate all position value differences. If one of those differences exceeds the `Threshold` value, the servos will be slowly moved to their new target position. This is done by sending multiple position values in small increments. During this process, the user interface will show a progress indicator.
160
+
To cancel this process you can either press `ESC` or click outside the dialog box. While position jump handling is not considered during the calibration process it is again considered when cancelling or applying the calibration.
120
161
121
-
### Serial Protocol
162
+
### Command Protocol
122
163
123
164
The position values are sent based on a specific binary protocol. The receiver has to know about it and be able to interpret the received data in order to successfully trigger the correct servo movement.
124
165
@@ -132,6 +173,6 @@ The protocol defines in which order and pattern individual bytes are transferred
132
173
133
174
The position value is split into 2 bytes (high and low), while the first byte is the most significant one.
134
175
135
-
### Reading Serial Commands on an Arduino
176
+
### Reading Commands on an Arduino
136
177
137
-
Instead of writing your own logic to read and interpret the serial commands, you can also use the [Blender Servo Animation Arduino Library](https://github.com/timhendriks93/blender-servo-animation-arduino) which has a built-in support for the live mode. Check out the library's repository for more details and some read-to-use examples.
178
+
Instead of writing your own logic to read and interpret the live mode commands, you can also use the [Blender Servo Animation Arduino Library](https://github.com/timhendriks93/blender-servo-animation-arduino) which has a built-in support for the live mode. Check out the library's repository for more details and some ready-to-use examples.
0 commit comments