Current Status: 

Main goal is functional, the Robot can be animated in real time, with an xbox (or similaer) controller, in animated sequences via Bottango, or in Bottango's "standalone driver" mode, which more closely mimics a seasonal decoration, and all animation lives on the microcontroller.

### Why did I do this?
- big fan of combining technology and story to create magic
- to learn the technologies involved
- to see if I could
- to have my own robot friend

### Who am I?
- 15+ years in Information Security as an "penetration tester" (hacked applications and networks managed by my employers)
- Raised in SoCal, big fan of animatronics, and in particular of the audioanimatronics featured in Disney Parks.

# How does it work?
## How it works (unmodified)
Yodas animations are triggered by a passive infrared sensor mounted to his robes, which can also be bypassed to use a contact-closure trigger (step-pad, remote, whatever) or be set to "lights only" mode, wherein he just kinda...wiggles around. I didn't spend much time in this mode. 

### Control Panel
Inside his control panel, yoda's animations are driven by a microctroller SoC from FMD. This soc is responsible for driving the left arm motor, the lightsaber LED, and passes off signals from audio recordings on the control board, off to Yoda's head via a 4-wire bus to his head. 

## Surgery: Opening Yoda's Head
There is not a way that I've found to get around this step: You're going to have to open up Yoda's head. This requires getting to 4 cross-head screws that are obscured by the silicone on the back of Yoda's head. 

The two screws nearest the neck's opening are within channels that can be seen through the opening of the neck, so it's pretty straight forward to follow them to their opening. The two near the top of Yoda's head are a little trickier, but you can feel them with your fingers if you're patient.

I was able to take a phillips screwdriver, with about a 3" reach, and pierce the silicone over each screw. I then unscrewed them, and then fought the stupid screws to make sure I didn't lose them.

With the 4 screws removed, the silicone covering is all that holds the two halves of the skull together. 

### Silicone Skin, ugh
Silicone is neat, and skin like in several ways. It's also a pain to have to glue things to. As everyone is quick to tell me, "Only silicone sticks to silicone". To get the skull halves apart, you can delicately separate the pieces along the seam, which is visible from the outside of the Skull, and travels along the path of the shell's seam. The silicone is glued together and is jammed within channels of the head shell. Larger pieces of silicone are bridged together to form a tab within the skull. If possible, try and keep those tabs intact, as they are important in reattaching the skin to the shell. 

[If you would like you glue the skin back together, you're going to need to buy a specialty silicone adhesive, such as Silpoxy. Note, this stuff is pricey, so have a plan when you use it.]

With some patience and practice, eventually you will be able to get the two halves of the shell apart. BE DELICATE WHEN YOU PULL THE TWO HALVES APART, THERE ARE WIRES CONNECTING THEM TOGETHER!

Now you can see the inner working of Master Yoda's 900 year old noodle: a smattering of servo wires, connecting up to a breakout board, which is also joined by a 2 wire motor connection for driving Yoda's mouth, and a 4 wire bus back to the main control panel. Sadly, this connector is NOT in fact i2c. It is +3v3, GND, Motor -, Data. Connecting my logic analyzer confirmed PWM on the Data wire, and these pins matched the silkscreen on the OEM control panel.

### Breakout within Yoda's Head

There, it connects to a breakout board, and is joined by 8 3-wire servos, which connect to the board in a **JST PH 2.0mm** 2.0 plug-end connector, as opposed to the traditional 3-wire Dupont style connector more commonly found on servos. 

The wires connecting to the breakout board are all smothered in a white glue, to anchor the servos in place and to discourage any tampering. But delicate scraping with a hobby knife allowed me to pick out the glue until the wire connectors were freed from the breakout. Note, don't use too much force, you may break stuff. If you've removed ALL of the glue the wire connectors will become unstuck with not much force.

### Servos
The 8 Servos are as follows:
 - Left Eye
 - Right Eye
 - Blink (both eyes)
 - Left Ear
 - Right Ear
 - Head Nod (Up down "yes")
 - Head turn
 - Head side to side

### Mouth Motor
You may have noticed, the mouth is not included within this list. Indeed, the mouth is driven by an integrated dc motor. When signal is applied, the mouth opens, and is closed by spring pressure when not energized. Audio signal is converted by the SoC on the main board to voltage using PWM (Pulse Width Modulation) and drives the mouth open and shut.

This is both great and frustrating. Common practice for 3-axis skulls would be to use a servo to drive the mouth as well, as they (typically) have 180-degrees range of motion with single-degree precision, allowing for much finer control over how wide the character's mouth will be opened.  Most show-control software (that I've experienced*) expects the mouth to be a servo. 

However, holiday electronics, like Yoda, from companies such as Gemmy and Seasonal Visions International, use the much-less expensive DC motor, which does not have the ability to return to fixed positions via precision control (degrees in the case of servos, and steps in the case of Stepper Motors). 

To get away with the fact that DC motors lack precision control beyond throttle and direction, most of these decorations use mechanical gimmicks to act as a compensating control. 

What this means to us holiday hardware hackers is that they've already thought of the details in most cases, and all we need to be concerned with is 1. making sure the motor is turning in the correct direction, and 2. That the motor is in sync with the audio. This will be important later, when we need to make him talk.

## How it works (post modification)
To have all of the same features as the unmodified decoration ("feature parity"), we will need to be able to have Master Yoda speak phrases and move in a life-like way. This will require the ability to play the sounds of our choice, drive servos, a dc motor, LEDs, and ideally provide the ability to expand as desired.

An Arduino-compatible microcontroller will serve as the brain of the robot, in this case an ESP32-S3 QtPy ($12.50 at Adafruit) but this was already in my collection. There are quite a lot of different options, some as low cost as $1 if you're patient. The microcontroller will start the playback of an audio file, and will drive the servos and the DC motor in sync with playback. 

### Playback of Audio
Playback will be handled in 1 of 2 ways:
For "standalone mode", which most accurately models how the decoration used to work, audio will be triggered via serial UART to a "YX5300" Serial MP3 module, which can be found for as low as $2 from AliExpress (or Amazon if you buy multiples). This module offloads the mp3 processing from the primary microcontroller, but at the expense of being a bit obtuse and hard to use in advanced scenarios Any serial mp3 player will work, include the more robust, but more expensive too, DFrobot DFPlayer mp3 module. 

The other reason for using serial mp3 modules for sound is that they're easy to integrated into the animation suite we will be using, Bottango. Bottango is primarily used to drive animatronics (and many other timed motors) to specific timings (often musical). In standalone mode, animation recordings are statically compiled into the arduino driver, allowing for completely standalone uses. Way cool! 

### Drive LEDs
This is basically the "Hello, world!" of microcontrollers, and more than easy enough for the ESP32-S3.

### Drive Servos
This is where things begin to get a little bit trickier. While efforts are still underway to properly gain control of code execution on the original yoda conotrol panel, efforts thus far have not met that objective. Driving the servos as they are also presents a challenge; the tires are terminated in the wrong kind of connector for most servo modules. Some modification will be required in order to use them for our purposes.

### Servo wires: Destructive or Non-destructive?
This step can be performed a variety of different ways, but we need to get the servo wires into the standard 3-wire Dupont connector. This is so that we may connect them to our servo controller board, a clone of [Adafruit's PCA9685](https://www.adafruit.com/product/815) 16 channel i2c servo control board.  You can generally find these online for about $10, less if you buy them in volume. I've seen them as low as $3 on AliExpress, but I'm a little wary of something those, buyer beware. 

This module allows us to connect our 8 (and up to 16) servos to the module instead of directly to the microcontroller. This saves us a LOT of wires (which is pretty important for the QtPy, which only has a few to begin with), and manages powering the servos without needing to draw them directly through the QtPy, which is sadly not up for the task. And in the event of a catastrophic failure (looking at you, discount $3 servo controller) the module provides a buffer of sorts between the fire and the ESP32.

The problem though is that the pins on the module are too close together for the type of connector on the wires in Yoda's head. This is because the distance between the pins, also known as the "pitch" is not the same (2.54 on the servo header, 2.0 on the Yoda wires). Also, the JST connector is much wider than that of the Dupont. All this to say, we need to cut the wires on the Yoda side, which is destructive and potentially irreversible, or we need to make a wiring harness. This requires a lot of soldering, as well as the materials to do so. 

While I am fairly comfortable soldering most things, I still struggle with wire-to-wire soldering, and the thought of having to do that while delicately navigating the cramped cavity of Yoda's betwixt plastic melon brought me to the conclusion that I was better off making those mistake on a wiring harness instead.  

I already had plenty of Dupont wires to harvest for connectors, but the JST PH 2.0 3 wire socket connector was a little more challenging, owing to most kits only providing the bare socket and some heat shrink tubing (If you need dupont wires, [this set on Amazon is reasonable at $9.99](https://www.amazon.com/OliYin-5-90inch-Extension-Aircraft-Stranded/dp/B07R14N3Z6?pd_rd_w=IpEPz&content-id=amzn1.sym.54a4b70b-6e28-4876-928a-df4db2e325f5&pf_rd_p=54a4b70b-6e28-4876-928a-df4db2e325f5&pf_rd_r=3Z49M6B27CFTX8MNQR6X&pd_rd_wg=ZODSG&pd_rd_r=325e04a8-c34a-4b04-9bc6-3de2521c3dc9&pd_rd_i=B07R14N3Z6&psc=1&ref_=pd_bap_d_grid_rp_0_1_ec_pd_gwd_bag_pd_gw_rp_4_i) for 20, and cut in half that gives you 40 to work with). This was beginning to sound like more cramped soldering, so I opted to source some pre-soldered wires instead. 
I settled on [this set](https://www.amazon.com/dp/B097GLZW5J?psc=1&ref=ppx_yo2ov_dt_b_product_details) of pre-crimped wire pigtails, which came with 40 connector end and 40 socket end wire pairs, plenty enough to get the job done. 

**

## WARNING! DANGER! FIRE!

**
Always always always check your wire colors and consult the datasheet whenever possible. The wires I got from Amazon used the same colors as Yoda's servos, but in a different order! If I had connected them together as expected, my robot would not have worked, and could possibly have created a fire hazard. Remember, friends: wires are liars! Trust, but verify! 

8 servos, three wires each, for a total of 24 soldering connections, if things went well. I planned on installing the PCA9685 on one of the mounting posts from the original board, which meant my wire leads needed to stay nice and short, so not a lot of room for mistakes. After 2 poorly soldered wire harnesses I decided to abandon soldering, and instead use heat-shrink wire connectors.  These are like the ones I used, Amazon has them for a few dollars in various wire sized. I used the smallest connectors, which were a snug fit, but the next size up was too loose.

If you've never used them before, here's a quick rundown of the process. 

 1. Strip off about 2mm of wire from each DuPont connector and JST PH pigtail (sometimes known as the "male" connector, not the socketed connector). 

 2. Insert the middle wire of the DuPont connector into one end of the wire splicer, and the middle wire of the JST connector goes in the opposite end of the splicer.  

Make sure the exposed wires pass through the blob of greasy glue, through the silvery solder ring, and so that they're touch one another in the center of the tube. 

 3. Use a heat gun or a lighter to *carefully* apply heat to the tube. The goal is to melt the solder rings until they liquify and flow together, bridging the connection for the two wires. 

Then when we remove heat, the solder hardens and the tubing makes a secure bond with the wires.  

Keep the heat moving in a circular motion to avoid scorching the wires. If you scorched any, check for continuity (beepy mode) with a Multimeter to ensure you have a solid electrical connection with the wires. 

To test for continuity (assuming your multimeter supports this mode), look for a mode that beeps when selected, often times looking like the symbol for Wifi, albeit sideways. This will produce an audible beep when the red and black probes are electrically connected. Touch the tips of the probes together: beep. Connected by wire? Beep. You get the idea. You should hear a beep when you put one probe on a pin within the Dupont connector (or the bit of metal shielding exposted under the connector) and the corresponding wire on the JST side. NOTE: If you used the headers I linked to, the wires will NOT be the same color on each end!

When you have 8 wire harnesses finished and fully tested, move on to installing them onto the servo wires in Yoda's head.

Drive DC Motor*

Feature Parity?

Parts Required:

# FAQ
### When is it available?
- Whenever you want to build one, my friend.

### How does it work?
 How did you get this far down into the README and not..  you know what, that's ok. 

I replaced the robot guts with open source modules. I use an awesome Open Source, FREE (free as in Freedom, AND free as in beer) software suite called Bottango. With Bottango I can animate the robot and feed it life.
Read about how, up here.

### Are you selling them?
Not at this time, no agreements in place w/ the myriad IP owners

### Where can I get my own?
See the "Additional Resources" section for links on where to acquire them, as of this writing.

### Can I hire you?

- Quite possibly, let's talk!

# Additional Resources

- Links
- Prior  work of those who came before
- Software, forums, discords that are useful/etc