Basic documentation

README.md

@@ -1,12 +1,76 @@
-# Fabula
+# 📖 Fabula
+
+Fabula is an open source and open hardware storyteller for children 1 to 8 yo.
+
+![3D Rendering](images/test_fit.png)
+![Exploded view](images/test_fit_exploded.png)
+
+It's a box with an inset where a plastic character can be snapped in place.
+When a character is snapped in place, Fabula starts playing the corresponding audio track(s).
+When the character is removed, the playback stops.
+There's a status led that provides some informations about the player (i.e. the battery level).
+The toy has an internal lithium-ion battery that can be charged via USB-C and provides 12h playback.
+It can also be monitored and controlled via Home Assistant or with a web interface in local network.
+It is privacy-friendly: it works completely localy and sends no data to any external service.
+
+## How does it work?
+
+![Take apart](images/take_apart.jpg)
+
+Every plastic character contains an NFC tag. The tag contains an integer from 1 to 99.
+Fabula contains an ESP8266 running ESPHome, a tag reader and an MP3 player that reads from a Micro SDCard.
+When an NFC tag is sensed, the integer is read and send to the MP3 player to start reading from the folder with that name.
+
+![Schematics](images/schematics.svg)
+
+## How to create a character
+
+
+![Character](images/character.jpg)
+
+
+### Program the TAG
+
+First of all, program the tag. I used adhesive "Mifare ultralight" tags.
+A valid tag should contain a single text field containing the name of the directory to play (a number between 01 and 99).
+You can use any app or device that supports NFC tags. I used "NFC Tools" for Android.
+> ⚠️ Test the tag with Fabula before enclosing it in the character!
+
+### Model the character
+
+Then, model the character:
+
+- Open `accessories/character_retainer_platform.scad` in OpenSCAD, import the model of the character you want to use and place it above the platform.
+- Render it (with `F6`)
+- Export as STL and open with your slicer
+- Slice it and look at the layers: notice there's an empty compartment hidden in the platform. It's where the NFC tag will be hidden.
+- Configure the slicer to pause the 3D printer before the layer that covers the empty compartment
+
+### Print it
+
+![Paused print with tag](images/character_nfc_tag.jpg)
+
+- Start the print, wait the printer to pause and insert an NFC tag in the compartment. Stick it using the adhesive side so the 3D printer cooling fan does not displace it during the print.
+- Restart the print and let it finish.
 
 ## NFC Tag format
 
 I used Mifare ultralight tags.
 A valid tag should contain a single text field containing the name of the directory to play (a number between 01 and 99).
 
+# Contributions
 
-## TODO:
+## Why isn't this hosted on GitHub?
 
-- [ ] Supportare pausa: salvare id cartella, quando si toglie il tag chiamare pause() e quando si mette il tag, verificare se numero cartella è uguale e chiamare start() oppure play_folder()
+I'm using a private git server just because I'm worried for the vast majority of open source code being hosted in a server property of Microsoft and being used to train theirs AI.
-- [ ] Salvare l'ultima traccia riprodotta per ogni cartella in una variabile che viene salvata (vedi restore_value in globals), quando rileva il tag della cartella riprendere dal file giusto. Gestire manualmente l'avanzamento al prossimo file, questo dovrebbe fixare il dfplayer.is_playing che ritorna False quando sta loopando dopo la prima traccia.
+I didn't find a better option, BTW the Gitea project is working on implementing federation, so soon it will be possible to contribute using any other gitea server, selfhosted or not.
+
+## How to contribute
+
+The project is open to contribution, but with some limits:
+
+- I'm sorry I can't accept AI-generated contributions. Reviewing a contribution requires time and effort from my side, while generating code with AI requires very little time and produces non reliable code that must be reviewed in detail. This is effectively shifting the work on my side, and in a forced way. If you feel you need a feature but you're not able to implement it by yourself, I prefer you to create an issue in the repository so I can implement it when I can, in a more mantainable way.
+- I prefer to make project-wide changes (i.e. updating Android target, app name and icon, release number...) by myself.
+
+To contribute, you'll have to create an account on this git instance. Unfortunately, I had to disable registration to avoid huge waves of fake accounts created by bots.
+You can request an account writing to daniele.verducci@ichibi.eu

accessories/manuelita.scad

@@ -0,0 +1,7 @@
+use <character_retainer_platform.scad>;
+
+character_retainer_platform();
+
+scale([0.65, 0.65, 0.65])
+    translate([-56, -60, 2])
+        import("/home/danieleverducci/Scaricati/GustavTheTurtle.stl");