M5Stick-crystal

Simple, stable, customizible, and extensible.

This firmware's structure follows the KISS principle. The code is extremely simple and structured. All functions use my wrappers, allowing you to quickly add new "programs" while focusing on the functionality itself, without wasting time interacting with the interface.

You can easily add a new function using the short guide or by looking on already created funcs in functions/ folder.

You can download firmware from M5Burner, build firmware by yourself or download binary from github releases (see the instructions below).

Install from M5Burner

You can use the M5Burner for simple firmware installation. Select m5stick in left side menu and start writing in the search line "Crystal".

Get latest build

🚀 Upcoming Features

• Add clock setting
• Add text size setting
• Add font style setting
• New languages
• Create new battery indicator
• Level tool based on gyro (why not?)
• Add NFC features
• Add IR features

🛠 Project Maintenance

• Structure functions, by the domain or by belonging to the category
• Create PID categories (like http status codes)
• Complete and structure the documentation
• Rerwrite to M5Unified
• Set up linting
• Rethract the web interface(beta)
• Support new devices

How to build?

Arduino CLI

Libraries:

arduino-cli lib install --git-url https://github.com/T-vK/ESP32-BLE-Keyboard

Compile:

arduino-cli compile --fqbn m5stack:esp32:m5stack_stickc_plus2 --build-path ./build -e --build-property build.partitions=huge_app --build-property upload.maximum_size=3145728 ./m5stick_crystal_firmware.ino

Merge binaries:

esptool --chip esp32s3 merge_bin --output build/firmware.bin 0x1000 build/m5stick_crystal_firmware.ino.bootloader.bin 0x8000 build/m5stick_crystal_firmware.ino.partitions.bin 0x10000 build/m5stick_crystal_firmware.ino.bin

Flash firmware:

esptool write_flash 0 build/firmware.bin

Arduino community edition

You can also use the extension arduino community edition for build and upload firmware in VS code.

Here is example of configuration files for this extension which I'm using:

.vscode/arduino.json

{
	"sketch": "m5stick_crystal_firmware.ino",
	"port": "/dev/ttyACM0",
	"board": "m5stack:esp32:m5stack_stickc_plus2",
	"output": "./build",
	"programmer": "esptool",
	"configuration": "PSRAM=enabled,PartitionScheme=default_8MB,CPUFreq=240,FlashMode=qio,FlashFreq=80,FlashSize=8M,UploadSpeed=1500000,LoopCore=1,EventsCore=1,DebugLevel=none,EraseFlash=none"
}

.vscode/settings.json

{
	"C_Cpp.intelliSenseEngine": "Tag Parser",
	"C_Cpp.default.includePath": [
		"${workspaceRoot}",
		"~/Arduino/libraries"
	],
	"arduino.enableUSBDetection": true,
	"arduino.additionalUrls": ["https://m5stack.oss-cn-shenzhen.aliyuncs.com/resource/arduino/package_m5stack_index.json"],
	"arduino.disableIntelliSenseAutoGen": true
}

How to add a new feature?

Add a menu item wherever you want. You must specify the name and number of the process that will be launched. You can take the first one available. Check the process id list.

functions/mainMenuLoop.h

MENU mainMenu[] = {
	// other items ...
	{40, "Hello world!"},
};

After that, create a function for the process, let's create a new file for this in the functions directory

functions/helloWorldLoop.h

void helloWorldLoop() {
	if (isSetup()) {
		centeredPrint("Hello world!", SMALL_TEXT);
	}
	checkExit(0);
}

In this code, we used functions, one of the “utilities”, necessary to make the code easier and cleaner. They are all located inside files in the utils directory. Some utilities are already described in the utilities documentation.

Add an include of this function next to the others.

globals/functions.h

// other includes...
#include "../functions/helloWorldLoop.h"

Finally, add your process to the processEntries array.

globals/switcher.h

const ProcessEntry processEntries[] = {
	// ...
	{40, helloWorldLoop},
}

✨ Result:

List of process IDs

0. mainMenu
1. clock
2. battery info
3. settingsMenu
4. Wi-Fi AP
5. brightness
6. rotation
7. colors
8. Wi-Fi scan
9. Wi-Fi network menu
10. settings statusBar
11. Wi-Fi deauth
12. Wi-Fi info
13. Wi-Fi Menu
14. Bluetooth Menu
15. Bluetooth camera shutter

Description of utilities

Only a small part of the utilities is described here

Utility name and description	Code example
isBtnBWasPressed isBtnAWasPressed Checks physical clicks and clicks from the web interface.	if (isBtnAWasPressed()) {Serial.print("btn A pressed!")}
pressBtnB pressBtnA Emulates a button press. You can try it with utility isBtn..WasPressed)	pressBtnA(); if (isBtnAWasPressed()) {Serial.print("btn A pressed!")}
isSetup Ensures that code within a condition is executed once when the program starts.	if (isSetup()) {Serial.print("run only ones!")}
checkExit If the user exits the program (presses button B) the process will be switched to the previous one (or pass the ID manually).	checkExit(3)
changeProcess Switches the process to the one passed in parameters	changeProcess(0)
setData Writes data to internal memory. Pass the key and value.	setData("brightness", 10);
getData Get data from internal memory. Pass a key, and a default value that will be returned if the data does not exist.	int brightness = 1; brightness = getData("brightness", brightness)
isWebDataRequested Checks whether a new line should be generated describing the current state of the interface. You will most likely need to pass the string "function" as the first argument. The second argument is a string that describes the contents of the interface.	if (isWebDataRequested()) {webData = generateWebData("function", generateFunctionElement("text", SMALL_TEXT, "center"));}
generateFunctionElement Creates and returns a string that describes the text parameters to be displayed inside the web interface. The first parameter is a line with text, the second is size, the third is centering. The resulting strings can be combined.	generateFunctionElement("text", SMALL_TEXT, "center") // return "text,2,center;"

Web interface screenshot:

❤️ Support my project with a star if you liked it. Contributing is welcome.

I need your support and experience in contributing. Any form of assistance is welcome. Ask any questions through Issues or Disscusions.