doc: script v1

README.md

@@ -0,0 +1,131 @@
+# Video script
+
+## Prep
+- Uninstall Arduino IDE on Fedora
+- Fresh Virtual Machine, under Virtual Machine Manager:
+  - TL;DR Ubuntu 24.04 Live Session (no install needed)
+  - `cp -v -t ~/.local/share/libvirt/images/ ~/Downloads/ubuntu-24.04-desktop-amd64.iso` for ISO location
+  - User session of QEMU
+  
+## Preface
+
+> In this video, I will show you how to install the Arduino legacy IDE
+> on Ubuntu 24, and Fedora 39. These instructions should work exactly
+> with slightly older versions of each OS, and with derivative
+> versions like Linux Mint or Rocky Linux 9. They should also work
+> generally with any Linux distributions which support installing
+> packages from Flathub or Snapcraft (flatpaks or snaps).
+
+> As described on Linsight.org, the new version 2 of the Arduino IDE
+> is a refactor that currently has some bugs. To support the LiBCM
+> update process, Linsight has opted to continue to use the Arduino
+> Legacy IDE. Because Linux distributions keep their system packages
+> up-to-date as part of their release cycle, their versions of certain
+> software dependenies have updated beyond what the Arduino Legacy IDE
+> will work well with.
+
+> To solve this, Linux packaging organizations like Snapcraft and
+> Flathub, which continue to offer the Arduino Legacy IDE, also
+> install a runtime environment to support the IDE. This means that
+> using the system software GUI on distributions like Ubuntu, Debian,
+> Fedora or Manjaro to install the IDE will "just work", even when the
+> instructions on arduino.cc will not.
+
+## Installing Arduino IDE: Ubuntu
+
+> On Ubuntu, open the App Center and search for Arduino
+> IDE. Currently, the only option is the Legacy IDE. We are going to
+> leave the selected channel on the stable version of 1.8.19 - note
+> this version of the IDE was released in Dec 2021 and will likely not
+> see another version bump.
+
+> Click *Install* > *Authenticate*. Once it is done installing, click
+> Open. You will be notified that without access to the `dialout`
+> group, your user will not be able to control serial devices in order
+> to flash Arduino boards, and will give you some instructions for how
+> to change that permission, including a reboot step. I am going to
+> ignore that for now, but you should take time to follow those steps
+> at this point.
+
+## Installing the Arduino IDE: Fedora
+
+> On Fedora, open the Software app, and in the top-left corner,
+> search for Arduino IDE. Flathub has begun packaging the v2 IDE, for
+> Fedora, but we're going to ignore that and click on the regular
+> Arduino IDE, then click "Install".
+
+> I have already modified my system so that my user is in the dialout
+> group:
+
+(Open terminal and show this)
+
+> ... You will encounter a similar prompt as with the Ubuntu
+> installation process, instructing you on how you can add your user
+> to the dialout secondary group. Do so.
+
+## Bonus: Compilation
+
+> This video is primarily oriented to users that are struggling with
+> the conflict of information between what is documented on
+> arduino.cc, and by downstream Linux packagers. The Arduino
+> organization likely recognizes there is not one right of using
+> Linux, and has as such not maintained their Linux install
+> instructions for use by the general public. However, since this
+> video was made in response to difficulties by LiBCM users to use
+> Linux to install LiBCM firmware updates, I am also going to show you
+> how to compile and update LiBCM.
+
+> To download the code, go to
+> https://github.com/doppelhub/Honda_Insight_LiBCM. This URL is
+> referenced elsewhere.
+
+> At this point, select the branch you want to install from. There are
+> two options you care about: the main branch, which is most stable,
+> and the prerelease branch, where you can check out the very latest
+> publicly-released changes.
+
+> Select the right branch in this dropdown, and then under Code, hit
+> "Download ZIP". Once this is done, you can extract the ZIP file
+> using a file browser.
+
+> As documented in the `Firmware Install - 1st Time` video, you will
+> need to edit the config.h file under `Honda_Insight_LiBCM` >
+> `Firmware` > `firmwareLiBCM` > `config.h`. Here, I'm using the
+> default Gnome text editor, and configuring LiBCM for basically the
+> minimum install - 5AhG3, small grid-charger, no current hack.
+
+## Compiling the firmware in the Arduino IDE
+
+> Now, I'm going to open the Arduino IDE I installed in a previous
+> step, and open the main LiBCM sketch we will be installing. Hit
+> "File", then "Open", then navigate to the extracted ZIP, then to the
+> Sketch (aka .ino) file, in `Firmware` > `firmwareLiBCM` >
+> `firmwareLiBCM.ino`.
+
+> You will also want to set the board to the Arduino Mega, so that the
+> compiler knows what kind of file to make. Under "Tools" > "Board",
+> select "Arduino Mega or Mega 2560".
+
+> Finally, to test compilation, hit the check-mark in the
+> top-left. As compilation proceeds, you may see warnings in the
+> output, but you can tell whether the compilation succeeded by
+> checking whether the compiler reports the ultimate size of the
+> sketch's program storage space and dynamic memory:
+
+> "Sketch uses 40062 bytes (15%) of program storage space" ...
+
+> ... and so on. At this point, so long as LiBCM is connected to your
+> computer via its black USB cable, connected to the Arduino IDE in
+> the Tools > Ports option, and as long as your system user is allowed
+> to use `dialout` group resources, firmware installation will
+> succeed, unless something has gone seriously wrong with LiBCM.
+
+## Future
+
+> If there's demand for it, I may make a short video showing some of
+> the things that may go wrong while connecting to LiBCM using a Linux
+> machine. Linux provides a lot of easily-accessible interfaces to
+> hardware that make it easy to tell how the computer is interacting
+> with USB devices, and over the years I've found it really helpful to
+> bisect issues down to hardware or software ones.
+