feat(i2c): add remote file management for schedule scripts

[matteraclement]

Remote File Management for Schedule Scripts via I2C

Summary

Add remote file management capabilities allowing the Raspberry Pi to upload, download, and delete schedule files (.wpi) on the Witty Pi 5 filesystem via I2C, without requiring USB mass storage access.

Motivation

Currently, managing schedule files requires either:

• Physically connecting USB and mounting the Witty Pi 5 as a mass storage device
• Direct filesystem access which isn't always practical in deployed systems

This feature enables programmatic file management from the Pi side, useful for:

• Remote schedule updates in headless/embedded deployments
• Automated schedule management scripts
• Integration with home automation systems

Changes

New Files

File	Purpose
src/file_admin.h	Header with status codes and file operation function declarations
src/file_admin.c	Implementation of FILE_UPLOAD, FILE_DOWNLOAD, FILE_DELETE commands
src/usb_msc_device.h	New header exposing USB MSC status and ejection functions

Modified Files

File	Changes
src/i2c.h	Added 3 new command defines, 6 interface function declarations
src/i2c.c	Added interface functions, increased buffer sizes (1KB → 4KB), added command handlers
src/usb_msc_device.c	Added usb_msc_ensure_ejected() helper function

Architecture & Key Design Decisions

1. Separate Module (No Circular Dependencies)

The file_admin module is isolated from script.c to avoid circular dependencies:

i2c.c → file_admin.c → fatfs_disk.c
                     → script.c (is_script_in_use only)

This keeps script parsing/scheduling logic separate from file management.

2. Protocol Consistency

New commands follow the existing delimiter-based protocol (<field|field|CRC>):

Command	Password	Cmd	Combined
FILE_UPLOAD	0xA3	0x55	0xA355
FILE_DOWNLOAD	0xA4	0x56	0xA456
FILE_DELETE	0xA5	0x57	0xA557

This matches existing LIST_FILES (0xA0F1) and CHOOSE_SCRIPT (0xA159) patterns.

3. Interface Functions (Proper Encapsulation)

Instead of extern declarations, buffer access is provided via accessor functions:

uint8_t* i2c_get_upload_buffer(void);
uint8_t* i2c_get_download_buffer(void);
void i2c_set_download_buffer_index(int index);

This allows file_admin.c to access buffers without exposing internal implementation details.

4. Security Measures

Threat	Mitigation
Path traversal	build_filepath() rejects / and \ in filenames
Arbitrary file write	Uploads restricted to /schedule directory only
Arbitrary file delete	Deletes restricted to /schedule directory only
Active script deletion	Explicit check prevents deletion of schedule.wpi, .act, .skd when running
Buffer overflow	All string operations have bounds checking

5. Buffer Size Increase

Buffers increased from 1KB to 4KB to support larger schedule files:

• Supports ~4000 bytes of file content
• Sufficient for ~395 schedule lines (though parser limits to 128)
• RAM impact: +6KB (RP2350 has 520KB SRAM)
• Compile-time validation via _Static_assert

6. USB MSC Coordination

Files operations automatically eject USB MSC if mounted to prevent filesystem corruption:

void usb_msc_ensure_ejected(void) {
    if (!ejected) {
        tud_msc_start_stop_cb(0, 0, false, true);
    }
}

This follows the existing pattern used by CHOOSE_SCRIPT and SYNC_CONF commands.

Protocol Details

Status Codes (written to I2C_ADMIN_CONTEXT 0x41)

Code	Constant	Meaning
0x00	ADMIN_STATUS_OK	Success
0x01	ADMIN_STATUS_FILE_NOT_FOUND	File not found
0x02	ADMIN_STATUS_CANNOT_DELETE_ACTIVE	Cannot delete active script
0x03	ADMIN_STATUS_IO_ERROR	I/O error
0x04	ADMIN_STATUS_INVALID_PACKET	Invalid packet format
0x05	ADMIN_STATUS_FILE_TOO_LARGE	File exceeds 4000 bytes
0x06	ADMIN_STATUS_INVALID_DIRECTORY	Invalid/restricted directory

Directory Restrictions

Operation	Allowed Directories
FILE_UPLOAD	/schedule only
FILE_DOWNLOAD	All (root, conf, log, schedule)
FILE_DELETE	/schedule only

Limitations

Limitation	Reason
Content cannot contain <, >, |	Delimiter-based protocol (matches existing commands)
Max file size 4000 bytes	Buffer size limit
No "active script name" query	System uses fixed paths; original filename discarded by design

Potential Breaking Changes to Examinate

modification of value of DOWNLOAD_BUFFER_SIZE and UPLOAD_BUFFER_SIZE

[uugear]

Thank you for submitting a high quality pull request.
We have reviewed your commit and also submited some suggested improvements. If you have questions or want to discuss some points, please post here.

[matteraclement]

Amazing ! This sould solve https://www.uugear.com/forums/technial-support-discussion/remote-update-of-schedule-on-wittypi5/

The main goal would be to lay the best possible fundations to allow https://github.com/uugear/Witty-Pi-5-Software to easily implement https://www.uugear.com/forums/technial-support-discussion/how-to-interact-programmatically-with-the-witty-pi-5-from-the-raspberry-pi/ . Do you see something else that has to (or should) be added here on the firmware side to allow perfect implementation on the Witty-Pi-5-Software side ?

[uugear]

With the newly implemented file managment, we believe the I2C interface already provides the necessary fundations.
There are different ways to process and use the data from I2C, and we don't want to make too much assumptions here.
Making an application to work as a data proxy may be a good idea, but we will not use wp5 to serve such purpose - that will never satisfy all users. Such application should be implemented by the user, to fully meet the needs.

[matteraclement]

Great if you think we already have the perfect abstraction level for this functionality with this, let's go !

As long as it unblocks https://www.uugear.com/forums/technial-support-discussion/how-to-interact-programmatically-with-the-witty-pi-5-from-the-raspberry-pi/ from being implemented in "software space" then it's a great addition already !

LGTM