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...

Table of Contents

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

Prerequisites and optional hardware

Depends on circuitpython 7. (7.3.x is the latest supported version as of now)
At the moment the supported microcontrollers are:

• Raspberry Pi Pico
  
• Raspberry Pi Pico W
  _{^{At the moment no CircuitPython uf2 image exists is instead relies on the normal Pico's uf2. This results to some bugs, the led & wifi don't work.}}
  
• Waveshare RP2040-Zero
  
• Adafruit KB2040
  
• Waveshare ESP32-S2-Pico
  
• Adafruit Feather ESP32-S2
  

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

Optional hardware compatible with ljinux:

• SSD1306 displays for a standalone display output
  
• ds1302 realtime clocks for persistent time (make sure to set fixrtc to false from the board's config file)
  
• sdcard breakout boards for more storage
  
• w5500 networking breakouts board for networking.
  

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

Note: Automatic Windows install not supported at the moment. Linux & MacOS only.

1. Install a supported CircuitPython version onto the board
   Raspberry Pi Pico uf2 file can be found here & detailed instructions regarding CircuitPython can be found here.
   
2. Clone (or download this repository) and from within the "source" folder, run make install.
   This command will automatically update the system files if they already exist.
   To only update the wanna-be kernel run make instead.
   (For these commands to work you need to have python3 installed, and the board attached & mounted.)
   
3. (Optional) Install the optional libraries for the hardware you want to connect to it.
   If you plan on using the board standalone, you don't need put any extra libraries in.
   
4. After these steps, eject the board and fully disconnect it from the pc. (It is important to power cycle it.)
   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: adafruit_wiznet5k adafruit_wsgi adafruit_requests adafruit_bus_device

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

Contributors

-> bill88t - @bill88t#4044
-> Marios - @mariospapaz#2188
-> mdaadoun - @mdaadoun#4475
-> markbirss
-> RetiredWizard

A complete Ljinux manual is available

https://github.com/bill88t/ljinux/blob/main/Manual.txt

Additional screenshots

Useful resources that helped with the development of this project

https://gist.github.com/fnky/458719343aabd01cfb17a3a4f7296797
https://en.wikipedia.org/wiki/ANSI_escape_code
https://github.com/todbot/circuitpython-tricks

More stuff will be added later as the project spirals into chaos.