Merge pull request #296 from brilliantlabsAR/compression-library

Compression library

Author: siliconwitch

source/application/Makefile

@@ -39,6 +39,7 @@ C_FILES += \
 	watchdog.c \
 	lua_libraries/bluetooth.c \
 	lua_libraries/camera.c \
+	lua_libraries/compression.c \
 	lua_libraries/display.c \
 	lua_libraries/file.c \
 	lua_libraries/imu.c \

source/application/compression.c

@@ -25,6 +25,45 @@
 #include <stdlib.h>
 #include "compression.h"
 #include "lz4.h"
+#include "nrfx_log.h"
+
+#define LZ4F_MAGICNUMBER 0x184D2204U
+#define LZ4F_MAGIC_SKIPPABLE_START 0x184D2A50U
+#define LZ4F_MIN_SIZE_TO_KNOW_HEADER_LENGTH 5
+#define LZ4F_HEADER_SIZE_MIN 7
+
+static uint32_t LZ4F_readLE32(const void *src)
+{
+    const uint8_t *const srcPtr = (const uint8_t *)src;
+    uint32_t value32 = srcPtr[0];
+    value32 |= ((uint32_t)srcPtr[1]) << 8;
+    value32 |= ((uint32_t)srcPtr[2]) << 16;
+    value32 |= ((uint32_t)srcPtr[3]) << 24;
+    return value32;
+}
+
+size_t LZ4F_headerSize(const void *src, size_t srcSize)
+{
+    /* minimal srcSize to determine header size */
+    if (srcSize < LZ4F_MIN_SIZE_TO_KNOW_HEADER_LENGTH)
+        return -20;
+
+    /* special case : skippable frames */
+    if ((LZ4F_readLE32(src) & 0xFFFFFFF0U) == LZ4F_MAGIC_SKIPPABLE_START)
+        return 8;
+
+    /* control magic number */
+    if (LZ4F_readLE32(src) != LZ4F_MAGICNUMBER)
+        return -21;
+
+    /* Frame Header Size */
+    {
+        uint8_t const FLG = ((const uint8_t *)src)[4];
+        uint32_t const contentSizeFlag = (FLG >> 3) & 0x01;
+        uint32_t const dictIDFlag = FLG & 0x01;
+        return LZ4F_HEADER_SIZE_MIN + (contentSizeFlag ? 8 : 0) + (dictIDFlag ? 4 : 0);
+    }
+}
 
 int compression_decompress(size_t destination_size,
                            const void *source,
@@ -34,18 +73,24 @@ int compression_decompress(size_t destination_size,
 {
     int status = 0;
 
+    size_t header_size = LZ4F_headerSize(source, source_size);
+
+    if (header_size < 0)
+    {
+        return header_size;
+    }
+
     char *output_buffer = malloc(destination_size);
+
     if (output_buffer == NULL)
     {
         return -1;
     }
 
-    // TODO the frame header might not be 7
-    char *block_pointer = (char *)source + 7;
+    char *block_pointer = (char *)source + header_size;
 
     while (1)
     {
-
         int current_block_size = ((uint8_t)block_pointer[0]) +
                                  ((uint8_t)block_pointer[1] << 8) +
                                  ((uint8_t)block_pointer[2] << 16) +

source/application/lua_libraries/compression.c

@@ -0,0 +1,128 @@
+/*
+ * This file is a part of: https://github.com/brilliantlabsAR/frame-codebase
+ *
+ * Authored by: Raj Nakarja / Brilliant Labs Ltd. (raj@brilliant.xyz)
+ *              Rohit Rathnam / Silicon Witchery AB (rohit@siliconwitchery.com)
+ *              Uma S. Gupta / Techno Exponent (umasankar@technoexponent.com)
+ *
+ * ISC Licence
+ *
+ * Copyright © 2025 Brilliant Labs Ltd.
+ *
+ * Permission to use, copy, modify, and/or distribute this software for any
+ * purpose with or without fee is hereby granted, provided that the above
+ * copyright notice and this permission notice appear in all copies.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+ * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+ * AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+ * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+ * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+ * OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+ * PERFORMANCE OF THIS SOFTWARE.
+ */
+
+#include <string.h>
+#include "compression.h"
+#include "frame_lua_libraries.h"
+#include "lauxlib.h"
+#include "lua.h"
+#include "watchdog.h"
+
+static int registered_function = 0;
+static uint8_t decompression_buffer[4096];
+static size_t decompression_buffer_size = 0;
+
+static void decompression_lua_handler(lua_State *L, lua_Debug *ar)
+{
+    sethook_watchdog(L);
+
+    if (registered_function != 0)
+    {
+        lua_rawgeti(L, LUA_REGISTRYINDEX, registered_function);
+
+        lua_pushlstring(L,
+                        (char *)decompression_buffer,
+                        decompression_buffer_size);
+
+        if (lua_pcall(L, 1, 0, 0) != LUA_OK)
+        {
+            luaL_error(L, "%s", lua_tostring(L, -1));
+        }
+    }
+}
+
+static void process_function_callback(void *context,
+                                      void *data,
+                                      size_t data_size)
+{
+    decompression_buffer_size = data_size;
+    memcpy(decompression_buffer, data, data_size);
+
+    lua_sethook(L_global,
+                decompression_lua_handler,
+                LUA_MASKCALL | LUA_MASKRET | LUA_MASKLINE | LUA_MASKCOUNT,
+                1);
+}
+
+static int lua_compression_register_process_function(lua_State *L)
+{
+    if (lua_isnil(L, 1))
+    {
+        registered_function = 0;
+        return 0;
+    }
+
+    if (lua_isfunction(L, 1))
+    {
+        registered_function = luaL_ref(L, LUA_REGISTRYINDEX);
+        return 0;
+    }
+
+    luaL_error(L, "expected nil or function");
+
+    return 0;
+}
+
+static int lua_compression_decompress(lua_State *L)
+{
+    size_t length;
+    const char *data = luaL_checklstring(L, 1, &length);
+
+    lua_Integer block_size = luaL_checkinteger(L, 2);
+
+    if (block_size <= 0)
+    {
+        luaL_error(L, "bytes must be greater than 0");
+    }
+
+    int status = compression_decompress(block_size,
+                                        data,
+                                        length,
+                                        process_function_callback,
+                                        NULL);
+
+    if (status)
+    {
+        luaL_error(L, "decompression failed");
+    }
+
+    return 0;
+}
+
+void lua_open_compression_library(lua_State *L)
+{
+    lua_getglobal(L, "frame");
+
+    lua_newtable(L);
+
+    lua_pushcfunction(L, lua_compression_register_process_function);
+    lua_setfield(L, -2, "process_function");
+
+    lua_pushcfunction(L, lua_compression_decompress);
+    lua_setfield(L, -2, "decompress");
+
+    lua_setfield(L, -2, "compression");
+
+    lua_pop(L, 1);
+}

source/application/lua_libraries/frame_lua_libraries.h

@@ -33,6 +33,7 @@ void lua_bluetooth_data_interrupt(uint8_t *data, size_t length);
 
 void lua_open_bluetooth_library(lua_State *L);
 void lua_open_camera_library(lua_State *L);
+void lua_open_compression_library(lua_State *L);
 void lua_open_display_library(lua_State *L);
 void lua_open_imu_library(lua_State *L);
 void lua_open_led_library(lua_State *L);

source/application/luaport.c

@@ -99,6 +99,7 @@ void run_lua(bool is_paired)
     lua_open_imu_library(L);
     lua_open_time_library(L);
     lua_open_led_library(L);
+    lua_open_compression_library(L);
 
     lua_open_file_library(L, !is_paired);
 

tests/test_compression.py

@@ -0,0 +1,49 @@
+import asyncio
+from frameutils import Bluetooth
+
+
+async def main():
+
+    b = Bluetooth()
+
+    await b.connect(print_response_handler=lambda s: print(s))
+
+    # Upload the Lua script
+    lua_script = """
+        -- Decompression function
+        function decomp_func(data)
+            print(data)
+        end
+
+        -- Register the decompression function
+        frame.compression.process_function(decomp_func)
+
+        -- Function to handle the compressed data received from Bluetooth
+        function ble_func(data)    
+            frame.compression.decompress(data, 1024)
+        end
+
+        -- Register the Bluetooth receive callback
+        frame.bluetooth.receive_callback(ble_func)
+
+    """
+
+    await b.upload_file(lua_script, "main.lua")
+    await b.send_reset_signal()
+
+    await asyncio.sleep(1)
+
+    # Send the compressed data. Here the total size of the data is is pretty small,
+    # but usually you would want to split the data into MTU sized chunks and stitch
+    # them together on the device side before decompressing.
+    compressed_data = bytearray(
+        b"\x04\x22\x4d\x18\x64\x40\xa7\x6f\x00\x00\x00\xf5\x3d\x48\x65\x6c\x6c\x6f\x21\x20\x49\x20\x77\x61\x73\x20\x73\x6f\x6d\x65\x20\x63\x6f\x6d\x70\x72\x65\x73\x73\x65\x64\x20\x64\x61\x74\x61\x2e\x20\x49\x6e\x20\x74\x68\x69\x73\x20\x63\x61\x73\x65\x2c\x20\x73\x74\x72\x69\x6e\x67\x73\x20\x61\x72\x65\x6e\x27\x74\x20\x70\x61\x72\x74\x69\x63\x75\x6c\x61\x72\x6c\x79\x3b\x00\xf1\x01\x69\x62\x6c\x65\x2c\x20\x62\x75\x74\x20\x73\x70\x72\x69\x74\x65\x49\x00\xa0\x20\x77\x6f\x75\x6c\x64\x20\x62\x65\x2e\x00\x00\x00\x00\x5f\xd0\xa3\x47"
+    )
+
+    await b.send_data(compressed_data)
+
+    await b.send_break_signal()
+    await b.disconnect()
+
+
+asyncio.run(main())