Skip to content

Commit

Permalink
move apps
Browse files Browse the repository at this point in the history
  • Loading branch information
@xMasterX
xMasterX committed Jul 6, 2023
0 parents commit e7bdd1b
Show file tree
Hide file tree
Showing 146 changed files with 6,472 additions and 0 deletions.
21 changes: 21 additions & 0 deletions LICENSE
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
MIT License

Copyright (c) 2022 BlueChip

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
233 changes: 233 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,233 @@
# [FlipperZero] Wii Extension Controller Protocol Analyser
This Protocol Analyser offers a full Test and Calibrate system for Wii Extension Controllers.

__Disclaimer:__ *Use of this plugin, and notably connecting an Extension Controller to the FlipperZero is performed entirely at your own risk.*

# Notes
This plugin has (todate) only been tested with official Nintendo Nunchucks and Classic Controllers - namely Nunchucks and Classic Controllers.

# Encryption
This plugin has SOME code to handle encryption, but it it unused, untested, and some of it is known to un-work.

This plugin (currently) only works with Extension Controllers which implement the encryption-bypass strategy. IE. `i2c_write(0xf0, 0x55) ; i2c_write(0xfb, 0x00)`

If you need this functionality, either raise an Issue or, better still, a Pull Request.

# Screen: SPLASH
<img src="_images/SPLASH.png" width="256"/><br/>
The SPLASH Screen is displayed when the Plugin starts. It can be cleared by pressing any key, else it will auto-clear after 3.5 seconds.

# Screen: WAIT
<img src="_images/WAIT.png" width="256"/>&nbsp;&nbsp;&nbsp;<img src="_images/Wiring.png" width="512"/><br/><br/>
The WAIT screen will display which pins you need to connect between the flipper and the Wii Extension Controller.

__Disclaimer:__ Use of this plugin, and notably connecting the Controller to the FlipperZero is performed entirely at your own risk.

Looking in to the exposed side of the Extension Controller plug, with the notch on the bottom

| EC Pin # | EC Position | EC Pin ID | Pin Function | FZ GPIO Pin Name | FZ GPIO Pin # |
| :---: | :---: | :---: | :---: | :---: | :---: |
| 1 | top-left | +3v3 | Power | 3v3 | 9 |
| 2 | bottom-left | SCL | i2c clock | C0 | 16 |
| 3 | top-centre | EN | ¿detect? | | |
| 4 | bottom-centre | -x- | -none- | | |
| 5 | top-right | SDA | i2c data | C1 | 15 |
| 6 | bottom-right | Gnd | Power | Gnd | 18 |

Keys:
* Left - Show splash screen
* Back - exit plugin

The easiest way to connect a Wii Extension Controller to a FlipperZero is arguably with a ["WiiChuck"](https://www.ebay.co.uk/sch/?_nkw=wiichuck) or a ["Nunchucky"](https://www.solarbotics.com/product/31040)<br/><br/>
<table style="border:none">
<tr><td><img src="_images/WiiChuck.png" width="166"/></td>
<td><img src="_images/Nunchucky.png" width="128"/></td></tr>
<tr><td align="center"><a href="https://www.ebay.co.uk/sch/?_nkw=wiichuck">WiiChuck</a></td>
<td align="center"><a href="https://www.solarbotics.com/product/31040">Nunchucky</a></td></tr>
</table>

### ** WARNING **
Neither the WiiChuck, nor the Nunchucky have a pin polarisation mechanism.<br/>
If you plug the adaptor in the wrong way around you WILL apply voltage to the Controller the wrong way round!!<br/>
I have no idea if THIS WILL PERMANENTLY KILL THE CONTROLLER ...Who wants to try it?

On all the WiiChucks I have seen:
* The WiiChuck has THREE connectors on one side, and TWO connectors on the other.
* The side with TWO connectors should go against the side of the Controller plug with the big indent.
```
+-------------+
| _________ |
| | = = = | |
| |_=_____=_| | <-- notice missing pin
| ___ |
| | | | <-- notice indent
+----+ +----+
```
<img src="_images/plug.png" width="128"/><br/>

...BUT I *highly* recommend you check the pins on your adaptor to make sure everything goes well.

I believe the unconnected pin on the top is a "presence detect" function, but I have not (yet) verified this.<br/>
This feature is NOT required by this plugin, as the detection is performed by means of an i2c handshake.

When a device is connected it will be immediately recognised. If it is not, either:
* The Controller is not correctly connected<br/>
...This may be as simple as a broken wire.
* The controller board in the Controller is faulty.<br/>
...Repair of which is beyond the scope of this document.

To get the list of "known" Controllers, run `./info.sh`<br/>
As of writing this, that returns:
```c
[PID_UNKNOWN ] = { {0x00, 0x00, 0x00, 0x00, 0x00, 0x00}, "Unknown Perhipheral", SCENE_DUMP,
[PID_NUNCHUCK ] = { {0x00, 0x00, 0xA4, 0x20, 0x00, 0x00}, "Nunchuck", SCENE_NUNCHUCK,
[PID_CLASSIC ] = { {0x00, 0x00, 0xA4, 0x20, 0x01, 0x01}, "Classic Controller", SCENE_CLASSIC,
[PID_BALANCE ] = { {0x00, 0x00, 0xA4, 0x20, 0x04, 0x02}, "Balance Board", SCENE_DUMP,
[PID_GH_GUITAR ] = { {0x00, 0x00, 0xA4, 0x20, 0x01, 0x03}, "Guitar Hero Guitar", SCENE_DUMP,
[PID_GH_DRUMS ] = { {0x01, 0x00, 0xA4, 0x20, 0x01, 0x03}, "Guitar Hero World Tour Drums", SCENE_DUMP,
[PID_TURNTABLE ] = { {0x03, 0x00, 0xA4, 0x20, 0x01, 0x03}, "DJ Hero Turntable", SCENE_DUMP,
[PID_TAIKO_DRUMS] = { {0x00, 0x00, 0xA4, 0x20, 0x01, 0x11}, "Taiko Drum Controller)", SCENE_DUMP,

```
You can see that there are EIGHT known devices. One is the default for an unknown controller; SEVEN devices are known by name; and TWO (of those seven) have bespoke "scenes" (ie. SCENE_NUNCHUCK & SCENE_CLASSIC).
# Screen: NUNCHUCK - MAIN
<img src="_images/NUNCHUCK.png" width="256"/><br/>
When you connect a Nunchuck, you will see a screen displaying:
* Accelerometer{X,Y,Z} values
* Joystick{X,Y} values
* Joystick graphic
* Button{C,Z}
Keys:
* Left - Go to the DUMP screen
* Right - Go to the NUNCHUCK_ACC accelerometers screen
* Up/Down/OK - [qv. Peak Meters]
* Short-Back - Reset controller
* Long-Back - Exit plugin
# Screen: NUNCHUCK - ACCELEROMETERS
<img src="_images/NUNCHUCK_anal.png" width="256" align="top"/>&nbsp;&nbsp;&nbsp;<img src="_images/NUNCHUCK_acc.png" width="200"/><br/>
| Axis | Movement | Lower | Higher |
| :---: | :---: | :---: | :---: |
| X | Left / Right | Left | Right |
| Y | Fwd / Bkwd | Fwd | Bkwd |
| Z | Down / Up | Down | Up |
* Movement in the direction of an axis changes that axis reading
* Twisting/tilting around an axis changes the other two readings
* EG.
* Move left (along the X axis) will effect X
* Turn left (a rotation around the Y axis) will effect X and Z
Keys:
* Left - go to the main NUNCHUCK screen
* Up
* Auto-Pause Disabled --> Enable Auto-Pause
* Paused at the end of a page --> Restart scanner
* Running with Auto-Pause Enabled --> Disable Auto-Pause
* Nunchuck-Z - Toggle pause
* Nunchuck-C - Toggle auto-pause
* Long-OK - Enter Software Calibration mode [qv. Calibration]
* Calibration mode on the Accelerometer screen will ONLY calibrate the accelerometer
* Short-OK - Leave Software Calibration mode *and* Calibrate CENTRE position(s)
* Short-Back - Reset controller
* Long-Back - Exit plugin
<sub>NB. Code DOES exist to scroll the display, but the LCD refresh rate is too low, and it looks awful</sub>
# Screen: CLASSIC
<img src="_images/CLASSIC.png" width="256"/><img src="_images/CLASSIC_N.png" width="256"/><br/>
When you connect a Classic Controller [Pro], you will see a screen displaying a Classic Controller
* The Classic Controller will animate in line with controller events
* The scan rate is set to 30fps, but in reality there is a bit of lag with the LCD screen, so YMMV.
Keys:
* Left - go to the DUMP screen
* Right - show analogue readings (Left to hide them again)
* Up/Down/OK - [qv. Peak Meters]
* Short-Back - Reset controller
* Long-Back - Exit plugin
# Screen: DUMP
<img src="_images/DUMP.png" width="256"/><br/>
The Dump screen will show you the raw readings from the device.<br/>
If you connect a device which does not have a bespoke `_decode()` function (etc.), you will see (only) this screen.
* SID - String ID - human-readable name (from the `info` table)
* PID - Peripheral ID - The 6 bytes which identify the device.
* Cal - Calibration data - 16 bytes
* The bottom row of hex shows the SIX bytes of Controller data
* Below each hex digit is the binary representation of that digit
* By example. With a Nunchuck connected, click the Z button, and watch the bit on the far right
Keys:
* Right - return to controller-specific screen (if there is one)
* Short-Back - Reset controller
* Long-Back - Exit plugin
# Peak Meters (Calibration values)
On any Controller-specific screen with a Peak/Trough menu displayed:
* Up - [toggle] only show peak values
* Down - [toggle] only show trough values
* Long-OK - Enter Software Calibration mode [qv. Calibration]
* Short-OK - Leave Software Calibration mode / Calibrate CENTRE position(s)
# Calibration
<img src="_images/NUNCHUCK_cal.gif" width="256"/><br/>
Digital buttons do NOT require Calibration.
Some controllers have Calibration data which is calculated at the factory, and stored in memory (¿OTP?) on the Controller.
EG. Classic Controller HAS Calibration data, but Classic Controller Pro does NOT!
Each device has a different way to interpret the Calibration Data.<br/>
EG. A Nunchuck has one joystick, and an accelerometer ...whereas a Classic Controller has 2 joysticks and 2 analogue buttons.
I have personally found the calibration data to be inaccurate (when compared to actual readings), I guess Controllers drift over the years‽
If the factory-values LIMIT movement, this is easily resolved - by expanding them on-the-fly.<br/>
BUT, I have seen Controllers with factory calibration data that suggests the limits are FURTHER than the joystick can reach ...and this requires a full re-calibration of the Controller!
Probably the best way to calibrate is to:
* Take a/some reading(s) while the Controller is 'at rest', IE. perfectly still and level.
* Move the Controller to all extremes and store the extreme {peak/trough} values.
Nintendo (allegedly) take the 'at rest' reading immediately after the Controller is connected, and a 're-calibration' can be performed at any time by pressing {`A`, `B`, `+`, `-`} at the same time, for at least 3 seconds. Although I have no details on what this actually does.
### This tool calibrates as such:
* When the Controller is first recognised
* The factory Calibration data is used to decide the Centre/Middle position and extreme values (eg. far-left & far-right) for each analogue Control
* Long-OK button press (on the FlipperZero) ...Do NOT touch ANY of the analogue controllers while you are pressing Long-OK
* Start the calibrate button flashing
* Take the current reading as the Centre position
* Set the range limits to "no range"
* You must now move the Control between its extremes, so the code can work out the new Calibration/range/peak+trough values
* When done, press Short-OK to end Software Calibration mode
* Short-OK button press (on the FlipperZero) ...Do NOT touch ANY of the analogue controllers while you are pressing Short-OK
* Stop the calibrate button flashing
* Calibrate the centre position of all analogue controls (accelerometers not supported (yet))
# Screen: DEBUG
<img src="_images/DEBUG.png" width="256"/><br/>
On any screen (except SPLASH) you may press Long-Down to enter Debug mode.
You can (at any time) attach to the FlipperZero (via USB) with a serial console {`minicom`, `putty`, whatever} and start the `log` function to see the debug messages.
When you enter the DEBUG screen, the real-time scanner will be stopped. And the following keys made available:
* Up - Attempt to initialise the attached Controller
* OK - Take a reading from the attached Controller
* Long-Down - Restart the real-time scanner and return to the WAIT screen
You can limit the messages at compile-time [see `./info.sh`], or at runtime [FZ->Settings->System->LogLevel]<br/>
[This is probably irrelevant since the introduction of FAP support]<br/>
If you have memory issues, limiting the messages at compile-time will make the plugin smaller.<br/>
But (¿obviously?) the more you limit the messsages, the less debug information will be sent to the logger.
# TODO
* FZ Bug: At the time of writing this, there are problems with the i2c FZ functions [qv `i2c_workaround.c`]
67 changes: 67 additions & 0 deletions README.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
,-------.
---( Files )---
`-------'

README.md - User Manual : Body [github markdown]
_images/ - User Manual : Images
_images/GIMP/ - User Manual : GIMP image masters

LICENSE - Tech Docs : MIT Licence file
README.txt - Tech Docs : Dev notes
notes.txt - Tech Docs : Random dev notes
info.sh - Tech Docs : Retrieve info from source code

application.fam - FAP : Header file
WiiEC.png - FAP : Icon {10x10}

gfx/ - Analyser : Images [generated by bc_image_tool]
wii_anal.c|h - Analyser : Main application
wii_anal_ec.c|h - Analyser : Extension controller actions
wii_anal_keys.c|h - Analyser : Keyboard handling
wii_anal_lcd.c|h - Analyser : LCD handling

i2c_workaround.h - Temporary workaround for i2c bug in FZ code
err.h - Errors
bc_logging.h - Logging macros - especially LOG_LEVEL

wii_i2c.c|h - i2c functionality

wii_ec.c|h - Extension Controller basic functions
wii_ec_macros.h - Bespoke Extension Controller handy-dandy MACROs
wii_ec_classic.c|h - EC: Classic Controller Pro scene
wii_ec_nunchuck.c|h - EC: Nunchuck scene
wii_ec_udraw.c|h - EC: UDraw scene - not written

,----------------------------------.
---( Adding a new Extension Controller )---
`----------------------------------'

//! I'll finish this when I write the UDraw code

Create a new Extension Controller called "mydev"

Create wii_ec_mydev.c and wii_ec_mydev.h

In wii_ec_mydev.c|h
Create the functions [& prototypes]
bool mydev_init (wiiEC_t* const) ; // Additional initialisation code
void mydev_decode (wiiEC_t* const) ; // Decode controller input data
void mydev_msg (wiiEC_t* const, FuriMessageQueue* const) ; // Put event messages in the event queue
void mydev_calib (wiiEC_t* const, ecCalib_t) ; // Controller calibration function
void mydev_show (Canvas* const, state_t* const) ; // Scene LCD display
bool mydev_key (const eventMsg_t* const, state_t* const) ; // Scene key controls

In wii_ec.h
Include the new header
#include "wii_ec_mydev.h"
Add a perhipheral id to enum ecPid
PID_MYDEV

In wii_anal.h
As a scene name to enum scene
SCENE_MYDEV

In wii_ec.c
Add the device definition to the ecId[] array
[PID_MYDEV] = { {0x00, 0x00, 0x00, 0x00, 0x00, 0x00}, "My Device", SCENE_MYDEV,
mydev_init, mydev_decode, mydev_msg, mydev_calib, mydev_show, mydev_key },
Binary file added WiiEC.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
21 changes: 21 additions & 0 deletions _image_tool/LICENSE
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
MIT License

Copyright (c) 2022 BlueChip

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
30 changes: 30 additions & 0 deletions _image_tool/README
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
1. Prepare the image
a. Open your *black and white* image in GIMP
b. File -> Export As
filename: EXAMPLE.c
Type : "C source code"
[Export]
prefixed name: gimp_image
Comment : <any>
[x] Use GLib types
[ ] <<all other options>>
Opacity : 100%
[Export]

2. Prepare conversion tool [stored in (eg.) /path/]
a. cp _convert*.* /path/
b. cp EXAMPLE.c /path/

3. Run the conversion tool
a. cd /path/
b. ./_convert.sh EXAMPLE.c

4. All being well, you will see an ascii version of your image.
If not, then you're gonna have to submit a bug report <shrug>

5. You should now have a directory called img_/
In that directory should be
img_EXAMPLE.c - The data for your new image
img_*.c - The data for other images
images.h - A header for ALL images that have been created in this directory
images.c - A sample FlipperZero show() function [not optimised]
Loading

0 comments on commit e7bdd1b

Please sign in to comment.