Ljinux

A "linux" written in python, for CircuitPython powered microcontrollers.

Important notes:
This project is still in it's early developement!
This project is NOT a linux distribution.
This project is NOT compatible with any linux code / binaries.

We also now have a discord server!
If you need support or want to hang out, feel free to join in!

We also work with Github Discussions.

Prerequisites
Installation / updating
Packages
Connection
Directory structure
Manual
Useful resources

Prerequisites and optional hardware

Runs on circuitpython 8.1.X and 8.2.X.
At the moment the supported boards are:

Raspberry Pi Pico
Raspberry Pi Pico W
Waveshare RP2040-Zero
Adafruit KB2040
Waveshare ESP32-S2-Pico
Adafruit Feather ESP32-S2
Adafruit Feather ESP32-S3 TFT
Pimoroni Pico Lipo (16mb)
Pimoroni Pico Lipo (4mb)
Wemos Lolin S2 Mini
Seeed XIAO nRF52840 (Sense)
DFRobot Beetle ESP32-C3
M5Stack Timer Camera X

But it can probably run on many more.
The only real limiting factor should be ram, as about 70k (usable under circuitpython) are needed.
(If you have gotten it running on an unsupported board, feel free to pr)

Installation / Updating

Note: Installation from windows is unsupported.

Install a supported CircuitPython version onto the board.
Detailed instructions regarding CircuitPython can be found here.
Download the latest ljinux release for your board and extract it onto it.
Or even better, if you wish to use the latest master, clone this repository and from within the "source" folder, run make install.
Installation from Windows is once again unsupported. If you are a bimbows user, this project isn't for you.
This command will automatically update the system files if they already exist.
To only update the wanna-be kernel run make instead.
If you wish to install to the CIRCUITPY drive directly, the board has to be attached and mounted.
If you plan on loading the files remotely (via web/ble workflow), run make *your board.board_id* install instead.
The files for you to copy will be created inside source/build_*your board.board_id*.
(Optional) Copy over the packages you wish to install with jpkg, or install drivers with make.
More info regarding packages in Packages
Eject & powercycle the board
When it's plugged back in, you can connect to it via serial.
(You can use putty to connect to the board on Windows, Tio or GNU/Screen on Linux or MacOS)
IMPORTANT NOTE: To make the board appear again as a usb drive on the host, run the ljinux command devmode

Packages

Some of ljinux's features are not bundled with this install.
You will have to install them seperately through the jpkg package manager.

You can find ljinux packages in the jpkg github topic.

Recommended packages:

Farland, the ljinux display manager: https://github.com/bill88t/ljinux-farland
SSD1306 display support: https://github.com/bill88t/ljinux-ssd1306
RubberDucky script support: https://github.com/bill88t/ljinux-ducky
Hashutils, md5 / sha commands: https://github.com/bill88t/ljinux-hashutils

Connection

To connect to the board it's recommended to use Putty for Windows and Tio for Linux/MacOS.

For Putty, select connection type to be Serial, select the port to be COMX where X is the number of the serial port allocated by the board and set the speed/baudrate to 115200.
(You can find which com port is allocated from within the Device Manager, it usually is COM3 or COM4)
(The baudrate may differ for your board, do not explicitly stick to 115200)

For Tio, if you are on linux, you need to be in the dialout or uucp user group and to connect, run: tio /dev/ttyACM0
If you are on a Mac instead, run: ls /dev/tty.usb* to find the device name, and connect to it by running: tio /dev/tty.usb<Device name here>
To disconnect, press Ctrl + t, q.
To be added to the dialout group, run sudo usermod -a -G dialout <your username here> and restart.

Directory structure

LjinuxRoot, the root filesystem for ljinux. It should be copied as is to the board.
rootfilesystem, the files needed in the root of the board. These should also be copied as is.
scripts, the files needed for compilation, and installation to a board. They should not be copied over,
source, the source files for ljinux and co. They should be compiled into .mpy files and put in /lib of the board.
packages, ljinux featured packages and preinstalled software, coming soon.
other, miscellaneous files