Ljinux

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

Important notes:
Do not take this project seriously.
This is not a real os / linux distribution, but here we are.
Also, it's still in an alpha state.

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

Anyways, since you are still reading...

Prerequisites
Installation / updating
Configuration
Connection
Directory structure
Contributors
Manual
Useful resources

Prerequisites and optional hardware

Runs on circuitpython 7.3.X or 8.0.X.
At the moment the supported microcontrollers are:

Raspberry Pi Pico
Raspberry Pi Pico W
Notice: Wifi doesn't work just yet.
Waveshare RP2040-Zero
Adafruit KB2040
Waveshare ESP32-S2-Pico
Adafruit Feather ESP32-S2
Pimoroni Pico Lipo (16mb)

But it can probably run on many more.
The only real limiting factor should be ram, as about 100k are needed for the system function.
(If you have gotten it running on an unsupported board, feel free to pr a configuration folder)

Optional hardware compatible with ljinux:

SSD1306 displays for display output
sdcard breakout boards for more storage
~~w5500 networking breakouts board for networking.~~ Temporarily broken.

For the missing hardware the functions will be automatically deactivated. (The hardware will also be deactivated in case of missing libraries.)
It expects to find a /LjinuxRoot folder which uses as it's root. It can be on the built in fs, or an sd card.
More info in Configuration.

Ljinux's shell is named based and is equivelant to gnu bash.
Python commands can also be used with the pexec command.
Whole .py files can be run with the use of the fpexec command.
They all run in the same scope as ljinux for ease of use. Security is not a priority on a microcontroller. Especially at the cost of ram.
You can connect to it over usb serial, or by providing startup commands via a Init.lja file.
The Init.lja has to be at /LjinuxRoot/boot/ of the board's internal storage or on the /boot/ of the attached sd card.
It has it's own curses library, jcurses.
And it's own display "compositor", farland.

Installation / Updating

Install a supported CircuitPython version onto the board
Detailed instructions regarding CircuitPython can be found here.
Download the latest release for your board and extract it onto it.
Or alternatively, clone this repository and from within the "source" folder, run make install.
If you are on windows (Note: Windows install in beta.), run the windows-install.bat.
This command will automatically update the system files if they already exist.
To only update the wanna-be kernel run make instead.
(For this to work you need to have python3 installed, even on windows, and the board attached & mounted.)
(Optional) To include drivers to the installation run make device name.
The currently available drivers are: wifi, ~~w5500spi~~ (broken)
For windows, you can run instead the respective bat file.
Eject & power off the board. (This is an important step.)
When it's plugged back in, it should run automatically and you can connect to it via serial. (You can use putty on windows, or gnu/screen on gnu/linux)
An automated connection script exists in the form of make connection
IMPORTANT NOTE: To make the pi appear as a usb device on the host, run the ljinux command devmode

Configuration

Each board has it's own different pin configuration. You can see the defaults and modify them from the board's respecive config file.

Libraries needed for optional hardware:
For the SSD1306 display: adafruit_ssd1306 adafruit_framebuf
Sdcard: adafruit_sdcard adafruit_bus_device
The sdcard has to be formatted as Fat32 / Fat16 or equivelant.
Ethernet: Handled by make

The neccessary libraries can be found here
Download the zip (The 7.x-mpy variant), extract it & copy the libraries you want onto /lib of the board.

Connection

For an automated way on Linux/MacOS, run make connection. Manual way below.

To connect to the board it's recommended to use Putty for Windows and GNU/Screen 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)

For GNU/Screen, if you are on linux, you need to be in the dialout user group and to connect, run: screen /dev/ttyACM0 115200
If you are on a Mac instead, run: ls /dev/tty.usb* to find the device name, and connect to it by running: screen /dev/tty.usb<Device name here> 115200
Example: screen /dev/tty.usbmodem12210 115200

To disconnect, press Ctrl + A, K and confirm with y.
To be added to the dialout group, run sudo usermod -a -G dialout <your username here>

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