brilliant-msg 7.0.0__py3-none-any.whl

brilliant_msg/__init__.py

@@ -0,0 +1,24 @@
+"""
+brilliant_msg - Message Package defines Transmit- and Receive-related message classes and their associated Lua handlers for Brilliant Labs Frame and Halo devices (https://brilliant.xyz/)
+"""
+
+__version__ = "7.0.0"
+
+from .brilliant_msg import BrilliantMsg
+
+from .tx_auto_exp_settings import TxAutoExpSettings
+from .tx_capture_settings import TxCaptureSettings
+from .tx_code import TxCode
+from .tx_image_sprite_block import TxImageSpriteBlock
+from .tx_manual_exp_settings import TxManualExpSettings
+from .tx_plain_text import TxPlainText
+from .tx_sprite import TxSprite
+from .tx_sprite_coords import TxSpriteCoords
+from .tx_text_sprite_block import TxTextSpriteBlock
+
+from .rx_audio import RxAudio
+from .rx_auto_exp_result import RxAutoExpResult
+from .rx_imu import RxIMU
+from .rx_metering_data import RxMeteringData
+from .rx_photo import RxPhoto
+from .rx_tap import RxTap

brilliant_msg/brilliant_msg.py

@@ -0,0 +1,184 @@
+from typing import List
+from importlib.resources import files
+
+from brilliant_ble import BrilliantBle, BrilliantDeviceType
+from typing import Callable
+
+class BrilliantMsg:
+    """
+    A high-level library for interacting with Brilliant Labs Frame by passing structured messages
+    between a Frameside app and a hostside app.
+
+    """
+    def __init__(self):
+        """Initialize the BrilliantMsg class with a new BrilliantBle instance and a dictionary for registered data response handlers."""
+        self.ble = BrilliantBle()
+        self.data_response_handlers = {}
+
+    async def connect(self, initialize:bool=True):
+        """
+        Connect to the Frame device and optionally run the initialization sequence.
+
+        Args:
+            initialize (bool): If True, runs the break/reset/break sequence after connecting.
+                             Defaults to True.
+
+        Returns:
+            bool: True if connection and initialization were successful
+
+        Raises:
+            Any exceptions from the underlying BrilliantBle connection
+        """
+        try:
+            await self.ble.connect(data_response_handler=self._handle_data_response)
+
+            if initialize:
+                # Send break signal in case an application loop is running
+                await self.ble.send_break_signal()
+
+                # Reset signal to restart Lua VM and initialize memory
+                await self.ble.send_reset_signal()
+
+                # Another break signal in case of auto-starting main.lua
+                await self.ble.send_break_signal()
+
+            return True
+
+        except Exception as e:
+            # If anything fails during connection or initialization,
+            # ensure we're disconnected and re-raise the exception
+            if self.ble.is_connected():
+                await self.ble.disconnect()
+            raise e
+
+
+    async def disconnect(self):
+        """Disconnect from the Frame device"""
+        if self.ble.is_connected():
+            await self.ble.disconnect()
+
+    def is_connected(self):
+        """Check if currently connected to the Frame device."""
+        return self.ble.is_connected()
+
+    async def print_short_text(self, text:str=''):
+        """
+        Convenience wrapper around `frame.display.text()` that can only be used
+        prior to the main frame_app starting (e.g. immediately after connection).
+        """
+        sanitized_text = text.replace("'", "\\'").replace("\n", "")
+        lua_command = ""
+        if (self.ble.type == BrilliantDeviceType.FRAME):
+            lua_command = f"frame.display.text('{sanitized_text}',1,1);frame.display.show();print(0)"
+        else:
+            lua_command = f"frame.display.clear();frame.display.text('{sanitized_text}',50,50);print(0)"
+
+        await self.ble.send_lua(lua_command, await_print=True)
+
+    async def upload_stdlua_libs(self, lib_names: List[str]=['data'], minified: bool=True):
+        """Send the specified standard frame-msg Lua files to Frame that are used by the frame_app, e.g. ['data', 'camera'] """
+        for stdlua in lib_names:
+            suffix = ".min" if minified else ""
+            await self.ble.upload_file_from_string(files("brilliant_msg").joinpath(f"lua/{stdlua}{suffix}.lua").read_text(), f"{stdlua}{suffix}.lua")
+
+    async def upload_frame_app(self, local_filename: str, frame_filename: str='frame_app.lua'):
+        """ Send the main lua application from this project to Frame that will run the app (but doesn't run the file)"""
+        # We rename the file slightly when we copy it, although it isn't necessary
+        await self.ble.upload_file(local_filename, frame_filename)
+
+    async def start_frame_app(self, frame_app_name:str='frame_app', await_print:bool=True):
+        """
+        'require' the main lua file to run it
+
+        Note: This require() doesn't return - frame_app.lua has a main loop,
+        so we can't put a 'print(0)' after the require() statement and wait for it to print,
+        however if our main loop prints something (even a byte) once it has started up,
+        then the await_print can be used to determine that the frameside app is ready
+        rather than waiting for an app-dependent amount of time,
+        or sending messages to Frame too early.
+        Set await_print to False if the Frame app should be asynchronously started
+        and without waiting for any printed confirmation that the frameside app is ready.
+        """
+        await self.ble.send_lua(f"require('{frame_app_name}')", await_print=await_print)
+
+    async def stop_frame_app(self, reset=True):
+        """
+        Sends a break signal to terminate the running main loop on Frame, if applicable.
+        A custom app may prefer to send a specific TxCode to the Frameside app to instruct it
+        to shut down cleanly, but a break signal will also be caught by the exception handler
+        of the main loop and is enough to clean up the display, release memory etc.
+
+        If `reset` is True (default), then also send a reset signal that will reinitialize the Lua VM
+        and boot into a saved `main.lua`, if present.
+        """
+        await self.ble.send_break_signal()
+        if reset:
+            await self.ble.send_reset_signal()
+
+    def attach_print_response_handler(self, handler=print):
+        """Attach the print response handler so we can see stdout from Frame Lua print() statements"""
+        self.ble._user_print_response_handler = handler
+
+    def detach_print_response_handler(self):
+        """Detach the print response handler so we no longer see stdout from Frame Lua print() statements"""
+        self.ble._user_print_response_handler = None
+
+    async def send_message(self, msg_code: int, payload: bytes, show_me: bool=False) -> None:
+        """
+        Sends a structured message from hostside to the Frameside app, identified by the specified msg_code.
+        For example, if the frame_app is expecting a TxCaptureSettings message on msg_code 0x0d
+        to initiate a photo capture, you might send:
+        `frame.send_message(0x0d, TxCaptureSettings(resolution=720).pack())`
+        Wraps the brilliant_ble function of the same name
+        """
+        await self.ble.send_message(msg_code, payload, show_me)
+
+    def register_data_response_handler(self, subscriber, msg_codes: List[int], handler: Callable[[bytes], None]):
+        """
+        Register a handler for a subscriber that is interested in specific msg codes.
+
+        Args:
+            subscriber: The subscriber object.
+            msg_codes (List[int]): List of single byte msg codes the subscriber is interested in.
+            handler: The handler function to receive the data.
+        """
+        for code in msg_codes:
+            if code not in self.data_response_handlers:
+                self.data_response_handlers[code] = []
+            self.data_response_handlers[code].append((subscriber, handler))
+
+    def unregister_data_response_handler(self, subscriber):
+        """
+        Unregister a subscriber from receiving data responses.
+
+        Args:
+            subscriber: The subscriber object to unregister.
+        """
+        for code in list(self.data_response_handlers.keys()):
+            self.data_response_handlers[code] = [
+                (sub, handler) for sub, handler in self.data_response_handlers[code] if sub != subscriber
+            ]
+            if not self.data_response_handlers[code]:
+                del self.data_response_handlers[code]
+
+    async def _handle_data_response(self, data: bytes):
+        """
+        Internal method to handle incoming data responses and dispatch to the appropriate handlers.
+
+        Args:
+            data (bytes): The incoming data response.
+        """
+        if data:
+            msg_code = data[0]
+            if msg_code in self.data_response_handlers:
+                for subscriber, handler in self.data_response_handlers[msg_code]:
+                    # not awaited, synchronous call
+                    handler(data)
+
+    def __getattr__(self, name):
+        """
+        Delegate any unknown attributes to the underlying BrilliantBle instance.
+        This allows direct access to all BrilliantBle methods while keeping the
+        wrapper transparent.
+        """
+        return getattr(self.ble, name)

brilliant_msg/lua/audio.lua

@@ -0,0 +1,59 @@
+-- Module for sending raw PCM audio Data from Frame's microphone
+local _M = {}
+
+-- Frame to Host flags
+local AUDIO_DATA_FINAL_MSG = 0x06
+local AUDIO_DATA_NON_FINAL_MSG = 0x05
+
+-- 1 byte reserved for flag
+local MTU = frame.bluetooth.max_length() - 1
+-- data buffer needs to be even for reading from microphone
+if MTU % 2 == 1 then MTU = MTU - 1 end
+
+function _M.start(args)
+	-- if args provides a sample_rate or a bit_depth use them otherwise use the defaults
+	local rate = (args and args.sample_rate) or 8000
+	local depth = (args and args.bit_depth) or 8
+
+	pcall(frame.microphone.start, {sample_rate=rate, bit_depth=depth})
+end
+
+function _M.stop()
+	pcall(frame.microphone.stop)
+end
+
+-- reads an MTU-sized amount of audio data and sends it to the host
+-- ensure this function is called frequently enough to keep up with realtime audio
+-- as the Frame buffer is ~32k
+function _M.read_and_send_audio()
+	audio_data = frame.microphone.read(MTU)
+
+	-- If frame.microphone.stop() is called, a nil will be read() here
+	if audio_data == nil then
+		-- send an end-of-stream message back to the host
+		while true do
+			-- If the Bluetooth is busy, this simply tries again until it gets through
+			if (pcall(frame.bluetooth.send, string.char(AUDIO_DATA_FINAL_MSG))) then
+				break
+			end
+		end
+
+		return nil
+
+	-- send the data that was read
+	elseif audio_data ~= '' then
+		while true do
+			-- If the Bluetooth is busy, this simply tries again until it gets through
+			if (pcall(frame.bluetooth.send, string.char(AUDIO_DATA_NON_FINAL_MSG) .. audio_data)) then
+				break
+			end
+		end
+
+		return string.len(audio_data)
+	end
+
+	-- no data read, no data sent
+	return 0
+end
+
+return _M

brilliant_msg/lua/audio.min.lua

@@ -0,0 +1 @@
+local a={}local b=0x06;local c=0x05;local d=frame.bluetooth.max_length()-1;if d%2==1 then d=d-1 end;function a.start(e)local f=e and e.sample_rate or 8000;local g=e and e.bit_depth or 8;pcall(frame.microphone.start,{sample_rate=f,bit_depth=g})end;function a.stop()pcall(frame.microphone.stop)end;function a.read_and_send_audio()audio_data=frame.microphone.read(d)if audio_data==nil then while true do if pcall(frame.bluetooth.send,string.char(b))then break end end;return nil elseif audio_data~=''then while true do if pcall(frame.bluetooth.send,string.char(c)..audio_data)then break end end;return string.len(audio_data)end;return 0 end;return a

brilliant_msg/lua/battery.lua

@@ -0,0 +1,17 @@
+-- Module handling periodic battery level reports on a standard message code
+local _M = {}
+
+-- Frame to phone flags
+local BATTERY_MSG = 0x0c
+
+function _M.send_batt_if_elapsed(prev, interval)
+    local t = frame.time.utc()
+    if ((prev == 0) or ((t - prev) > interval)) then
+        pcall(frame.bluetooth.send, string.char(BATTERY_MSG) .. string.char(math.floor(frame.battery_level())))
+        return t
+    else
+        return prev
+    end
+end
+
+return _M

brilliant_msg/lua/battery.min.lua

@@ -0,0 +1 @@
+local _M={}local a=0x0c;function _M.send_batt_if_elapsed(b,c)local d=frame.time.utc()if b==0 or d-b>c then pcall(frame.bluetooth.send,string.char(a)..string.char(math.floor(frame.battery_level())))return d else return b end end;return _M

brilliant_msg/lua/camera.lua

@@ -0,0 +1,200 @@
+-- Module to encapsulate taking and sending photos as simple frame app messages
+local _M = {}
+
+-- Frame to phone flags
+local IMAGE_MSG = 0x07
+local IMAGE_FINAL_MSG = 0x08
+local AUTOEXP_DATA_MSG = 0x11
+local METERING_DATA_MSG = 0x12
+
+-- local state to capture the stateful camera settings
+local quality_values = {'VERY_LOW', 'LOW', 'MEDIUM', 'HIGH', 'VERY_HIGH'}
+local metering_values = {'SPOT', 'CENTER_WEIGHTED', 'AVERAGE'}
+
+-- default settings
+local auto_exp_settings = {
+	metering = 'CENTER_WEIGHTED',
+	exposure = 0.1,
+	exposure_speed = 0.45,
+	shutter_limit = 16383,
+	analog_gain_limit = 16.0,
+	white_balance_speed = 0.5,
+	rgb_gain_limit = 287
+}
+
+local manual_exp_settings = {
+	shutter = 4096,
+	analog_gain = 1,
+	red_gain = 121,
+	green_gain = 64,
+	blue_gain = 140
+}
+
+-- auto/manual status, accessible outside the module
+_M.is_auto_exp = true
+
+-- helper function to update settings if they are present (otherwise keep defaults)
+function update_if_present(settings, updates)
+    for k, v in pairs(updates) do
+        if v ~= nil then
+            settings[k] = v
+        end
+    end
+end
+
+-- Update the saved auto exposure settings with the provided args
+-- The caller still needs to _M.run_auto_exposure() every 100ms after this
+function _M.set_auto_exp_settings(args)
+	update_if_present(auto_exp_settings, args)
+	_M.is_auto_exp = true
+end
+
+-- Turns off auto exposure flag if present and updates the manual exposure settings with the provided args
+-- Sets the manual exposure settings into the camera using the low level functions
+function _M.set_manual_exp_settings(args)
+	_M.is_auto_exp = false
+	update_if_present(manual_exp_settings, args)
+
+	-- actually update the state of the camera
+	frame.camera.set_shutter(manual_exp_settings.shutter)
+	frame.camera.set_gain(manual_exp_settings.analog_gain)
+	frame.camera.set_white_balance(manual_exp_settings.red_gain, manual_exp_settings.green_gain, manual_exp_settings.blue_gain)
+end
+
+-- parse the auto exposure settings message from the host into a table we can use with set_auto_exp_settings()
+function _M.parse_auto_exp_settings(data)
+	local settings = {}
+
+	settings.metering = metering_values[string.byte(data, 1) + 1]
+	settings.exposure = string.byte(data, 2) / 255.0
+	settings.exposure_speed = string.byte(data, 3) / 255.0
+	settings.shutter_limit = string.byte(data, 4) << 8 | string.byte(data, 5) & 0x3FFF
+	settings.analog_gain_limit = string.byte(data, 6) & 0xFF
+	settings.white_balance_speed = string.byte(data, 7) / 255.0
+	settings.rgb_gain_limit = string.byte(data, 8) << 8 | string.byte(data, 9) & 0x3FF
+
+	return settings
+end
+
+-- parse the manual exposure settings message from the host into a table we can use with set_manual_exp_settings()
+function _M.parse_manual_exp_settings(data)
+	local settings = {}
+
+    settings.shutter = string.byte(data, 1) << 8 | string.byte(data, 2) & 0x3FFF
+	settings.analog_gain = string.byte(data, 3) & 0xFF
+	settings.red_gain = string.byte(data, 4) << 8 | string.byte(data, 5) & 0x3FF
+	settings.green_gain = string.byte(data, 6) << 8 | string.byte(data, 7) & 0x3FF
+	settings.blue_gain = string.byte(data, 8) << 8 | string.byte(data, 9) & 0x3FF
+
+	return settings
+end
+
+-- parse the capture settings message from the host into a table we can use with the capture_and_send function
+function _M.parse_capture_settings(data)
+
+	local settings = {}
+	-- quality and metering mode are indices into arrays of values (0-based phoneside; 1-based in Lua)
+	settings.quality = quality_values[string.byte(data, 1) + 1]
+	local half_res = string.byte(data, 2) << 8 | string.byte(data, 3)
+	settings.resolution = half_res * 2
+	local pan_shifted = string.byte(data, 4) << 8 | string.byte(data, 5)
+	settings.pan = pan_shifted - 140
+	settings.raw = string.byte(data, 6) > 0
+
+	return settings
+end
+
+-- send data with retries and no sleeps, bail after 2 seconds
+function send_data(data)
+	local sent = false
+
+	-- 2 second time limit for this packet else bail out
+	local try_until = frame.time.utc() + 2
+
+	while frame.time.utc() < try_until do
+		if pcall(frame.bluetooth.send, data) then
+			sent = true
+			break
+		end
+	end
+
+	if not sent then
+		error('Error sending photo data')
+	end
+end
+
+-- Runs the auto exposure algorithm with the current settings (call this every 100ms)
+function _M.run_auto_exposure()
+	-- pass the table into the function with parentheses, don't wrap again in curly braces, it's already a table
+	return frame.camera.auto(auto_exp_settings)
+end
+
+function _M.send_autoexp_result(autoexp)
+	-- Pack the message code as an unsigned byte (B)
+    -- followed by 16 floats (f) in little-endian format
+    local data = string.pack("<Bffffffffffffffff",
+		AUTOEXP_DATA_MSG,
+        -- Top level values
+        autoexp['error'],
+        autoexp['shutter'],
+        autoexp['analog_gain'],
+        autoexp['red_gain'],
+        autoexp['green_gain'],
+        autoexp['blue_gain'],
+
+        -- Brightness values
+        autoexp['brightness']['center_weighted_average'],
+        autoexp['brightness']['scene'],
+
+        -- Brightness matrix values
+        autoexp['brightness']['matrix']['r'],
+        autoexp['brightness']['matrix']['g'],
+        autoexp['brightness']['matrix']['b'],
+        autoexp['brightness']['matrix']['average'],
+
+        -- Brightness spot values
+        autoexp['brightness']['spot']['r'],
+        autoexp['brightness']['spot']['g'],
+        autoexp['brightness']['spot']['b'],
+        autoexp['brightness']['spot']['average']
+    )
+
+    -- Total size: 1 byte for message code + (16 floats * 4 bytes) = 65 bytes
+	send_data(data)
+end
+
+-- send the current spot and matrix rgb values from the FPGA (as used by the auto exposure algorithm)
+function _M.send_metering_data()
+	send_data(string.char(METERING_DATA_MSG) .. frame.fpga_read(0x25, 6))
+end
+
+-- takes a capture_settings table and sends the image data to the host
+function _M.capture_and_send(args)
+	frame.camera.capture { resolution=args.resolution, quality=args.quality, pan=args.pan }
+
+	-- wait until the capture is finished and the image is ready before continuing
+	while not frame.camera.image_ready() do
+		frame.sleep(0.005)
+	end
+
+	local data = ''
+	local raw = args.raw
+
+	while true do
+		-- skip the 623 byte header if the caller requested raw data
+		if (raw) then
+        	data = frame.camera.read_raw(frame.bluetooth.max_length() - 1)
+		else
+        	data = frame.camera.read(frame.bluetooth.max_length() - 1)
+		end
+
+        if (data ~= nil) then
+			send_data(string.char(IMAGE_MSG) .. data)
+		else
+			send_data(string.char(IMAGE_FINAL_MSG))
+			break
+		end
+	end
+end
+
+return _M

brilliant_msg/lua/camera.min.lua

@@ -0,0 +1 @@
+local a={}local b=0x07;local c=0x08;local d=0x11;local e=0x12;local f={'VERY_LOW','LOW','MEDIUM','HIGH','VERY_HIGH'}local g={'SPOT','CENTER_WEIGHTED','AVERAGE'}local h={metering='CENTER_WEIGHTED',exposure=0.1,exposure_speed=0.45,shutter_limit=16383,analog_gain_limit=16.0,white_balance_speed=0.5,rgb_gain_limit=287}local i={shutter=4096,analog_gain=1,red_gain=121,green_gain=64,blue_gain=140}a.is_auto_exp=true;function update_if_present(j,k)for l,m in pairs(k)do if m~=nil then j[l]=m end end end;function a.set_auto_exp_settings(n)update_if_present(h,n)a.is_auto_exp=true end;function a.set_manual_exp_settings(n)a.is_auto_exp=false;update_if_present(i,n)frame.camera.set_shutter(i.shutter)frame.camera.set_gain(i.analog_gain)frame.camera.set_white_balance(i.red_gain,i.green_gain,i.blue_gain)end;function a.parse_auto_exp_settings(o)local j={}j.metering=g[string.byte(o,1)+1]j.exposure=string.byte(o,2)/255.0;j.exposure_speed=string.byte(o,3)/255.0;j.shutter_limit=string.byte(o,4)<<8|(string.byte(o,5)&0x3FFF)j.analog_gain_limit=string.byte(o,6)&0xFF;j.white_balance_speed=string.byte(o,7)/255.0;j.rgb_gain_limit=string.byte(o,8)<<8|(string.byte(o,9)&0x3FF)return j end;function a.parse_manual_exp_settings(o)local j={}j.shutter=string.byte(o,1)<<8|(string.byte(o,2)&0x3FFF)j.analog_gain=string.byte(o,3)&0xFF;j.red_gain=string.byte(o,4)<<8|(string.byte(o,5)&0x3FF)j.green_gain=string.byte(o,6)<<8|(string.byte(o,7)&0x3FF)j.blue_gain=string.byte(o,8)<<8|(string.byte(o,9)&0x3FF)return j end;function a.parse_capture_settings(o)local j={}j.quality=f[string.byte(o,1)+1]local p=string.byte(o,2)<<8|string.byte(o,3)j.resolution=p*2;local q=string.byte(o,4)<<8|string.byte(o,5)j.pan=q-140;j.raw=string.byte(o,6)>0;return j end;function send_data(o)local r=false;local s=frame.time.utc()+2;while frame.time.utc()<s do if pcall(frame.bluetooth.send,o)then r=true;break end end;if not r then error('Error sending photo data')end end;function a.run_auto_exposure()return frame.camera.auto(h)end;function a.send_autoexp_result(t)local o=string.pack("<Bffffffffffffffff",d,t['error'],t['shutter'],t['analog_gain'],t['red_gain'],t['green_gain'],t['blue_gain'],t['brightness']['center_weighted_average'],t['brightness']['scene'],t['brightness']['matrix']['r'],t['brightness']['matrix']['g'],t['brightness']['matrix']['b'],t['brightness']['matrix']['average'],t['brightness']['spot']['r'],t['brightness']['spot']['g'],t['brightness']['spot']['b'],t['brightness']['spot']['average'])send_data(o)end;function a.send_metering_data()send_data(string.char(e)..frame.fpga_read(0x25,6))end;function a.capture_and_send(n)frame.camera.capture{resolution=n.resolution,quality=n.quality,pan=n.pan}while not frame.camera.image_ready()do frame.sleep(0.005)end;local o=''local u=n.raw;while true do if u then o=frame.camera.read_raw(frame.bluetooth.max_length()-1)else o=frame.camera.read(frame.bluetooth.max_length()-1)end;if o~=nil then send_data(string.char(b)..o)else send_data(string.char(c))break end end end;return a

brilliant_msg/lua/code.lua

@@ -0,0 +1,11 @@
+-- Module to parse message codes sent from phoneside app as TxCode messages
+local _M = {}
+
+-- Parse the TxCode message raw data, which is a single byte
+function _M.parse_code(data)
+	local code = {}
+	code.value = string.byte(data, 1)
+	return code
+end
+
+return _M

brilliant_msg/lua/code.min.lua

@@ -0,0 +1 @@
+local _M={}function _M.parse_code(a)local b={}b.value=string.byte(a,1)return b end;return _M

brilliant_msg/lua/data.lua

@@ -0,0 +1,128 @@
+-- Module containing generic data handling code.
+-- BLE packets with a specific message code are accumulated and concatenated,
+-- then enqueued in arrival order for the caller to parse and dispatch.
+local _M = {}
+
+-- accumulates chunks of input message into this table
+local app_data_accum = {}
+_M.app_data_accum = app_data_accum
+
+-- ordered queue of completed messages {msg_flag, block_data} in arrival order
+local app_data_queue = {}
+local app_data_queue_len = 0
+
+-- Data Handler: called when data arrives, must execute quickly.
+-- Update the app_data_accum item based on the contents of the current packet
+-- The first byte of the packet indicates the message type, and the item's key
+-- The first packet also has a Uint16 message length field right after the message type
+-- If the key is not present, initialise a new app data item
+-- Accumulate chunks of data of the specified type, for later processing
+-- The message codes and message length fields are not included in the accumulated chunks.
+-- When the message is fully received, the completed message is appended to the ordered queue
+-- so no need to pass on the length or message type in the payload
+-- TODO add reliability features (packet acknowledgement or dropped packet retransmission requests, message and packet sequence numbers)
+function _M.update_app_data_accum(data)
+    rc, err = pcall(
+        function()
+            local msg_flag = string.byte(data, 1)
+            local item = _M.app_data_accum[msg_flag]
+            if item == nil or next(item) == nil then
+                item = { chunk_table = {}, num_chunks = 0, size = 0, recv_bytes = 0 }
+                _M.app_data_accum[msg_flag] = item
+            end
+
+            if item.num_chunks == 0 then
+                -- first chunk of new data contains size (Uint16)
+                item.size = string.byte(data, 2) << 8 | string.byte(data, 3)
+                item.chunk_table[1] = string.sub(data, 4)
+                item.num_chunks = 1
+                item.recv_bytes = string.len(data) - 3
+
+                if item.recv_bytes == item.size then
+                    app_data_queue_len = app_data_queue_len + 1
+                    app_data_queue[app_data_queue_len] = {msg_flag, item.chunk_table[1]}
+                    item.size = 0
+                    item.recv_bytes = 0
+                    item.num_chunks = 0
+                    item.chunk_table[1] = nil
+                    app_data_accum[msg_flag] = item
+                end
+            else
+                item.chunk_table[item.num_chunks + 1] = string.sub(data, 2)
+                item.num_chunks = item.num_chunks + 1
+                item.recv_bytes = item.recv_bytes + string.len(data) - 1
+
+                -- if all bytes are received, concat and enqueue the completed message
+                if item.recv_bytes == item.size then
+                    collectgarbage('collect')
+                    app_data_queue_len = app_data_queue_len + 1
+                    app_data_queue[app_data_queue_len] = {msg_flag, table.concat(item.chunk_table)}
+                    for k, v in pairs(item.chunk_table) do item.chunk_table[k] = nil end
+                    collectgarbage('collect')
+                    item.size = 0
+                    item.recv_bytes = 0
+                    item.num_chunks = 0
+                    _M.app_data_accum[msg_flag] = item
+                end
+            end
+
+            -- send some data back as an ACK for receiver-paced flow control
+            -- and send_message() must use await_data=True
+            while true do
+                -- If the Bluetooth is busy, this simply tries again until it gets through
+                -- data/ack/success
+                if (pcall(frame.bluetooth.send, '\x01\x00\x00')) then
+                    break
+                end
+                frame.sleep(0.0025)
+            end
+
+        end
+    )
+    if rc == false then
+        -- send the error back on the stdout stream otherwise the data handler thread fails silently
+        print('Error in data accumulator: ' .. err)
+        while true do
+            -- If the Bluetooth is busy, this simply tries again until it gets through
+            -- data/ack/failure
+            if (pcall(frame.bluetooth.send, '\x01\x00\x01')) then
+                break
+            end
+            frame.sleep(0.0025)
+        end
+        -- rethrow the error, especially important to propagate the break signal to stop execution
+        error(err)
+    end
+end
+
+-- register the handler as a callback for all data sent from the host
+frame.bluetooth.receive_callback(_M.update_app_data_accum)
+
+-- Drains the ordered message queue.
+-- Returns an array of {flag, raw_block} pairs in arrival order.
+-- The caller is responsible for parsing and dispatching each item.
+function _M.process_raw_items()
+    local items = {}
+    local items_len = 0
+    rc, err = pcall(
+        function()
+            collectgarbage('collect')
+
+            for i = 1, app_data_queue_len do
+                items_len = items_len + 1
+                items[items_len] = app_data_queue[i]
+                app_data_queue[i] = nil
+            end
+
+            app_data_queue_len = 0
+        end
+    )
+    if rc == false then
+        print('Error processing raw items: ' .. err)
+        error(err)
+    end
+
+    return items
+end
+
+return _M

brilliant_msg/lua/data.min.lua

@@ -0,0 +1 @@
+local a={}local b={}a.app_data_accum=b;local c={}local d=0;function a.update_app_data_accum(e)rc,err=pcall(function()local f=string.byte(e,1)local g=a.app_data_accum[f]if g==nil or next(g)==nil then g={chunk_table={},num_chunks=0,size=0,recv_bytes=0}a.app_data_accum[f]=g end;if g.num_chunks==0 then g.size=string.byte(e,2)<<8|string.byte(e,3)g.chunk_table[1]=string.sub(e,4)g.num_chunks=1;g.recv_bytes=string.len(e)-3;if g.recv_bytes==g.size then d=d+1;c[d]={f,g.chunk_table[1]}g.size=0;g.recv_bytes=0;g.num_chunks=0;g.chunk_table[1]=nil;b[f]=g end else g.chunk_table[g.num_chunks+1]=string.sub(e,2)g.num_chunks=g.num_chunks+1;g.recv_bytes=g.recv_bytes+string.len(e)-1;if g.recv_bytes==g.size then collectgarbage('collect')d=d+1;c[d]={f,table.concat(g.chunk_table)}for h,i in pairs(g.chunk_table)do g.chunk_table[h]=nil end;collectgarbage('collect')g.size=0;g.recv_bytes=0;g.num_chunks=0;a.app_data_accum[f]=g end end;while true do if pcall(frame.bluetooth.send,'\x01\x00\x00')then break end;frame.sleep(0.0025)end end)if rc==false then print('Error in data accumulator: '..err)while true do if pcall(frame.bluetooth.send,'\x01\x00\x01')then break end;frame.sleep(0.0025)end;error(err)end end;frame.bluetooth.receive_callback(a.update_app_data_accum)function a.process_raw_items()local j={}local k=0;rc,err=pcall(function()collectgarbage('collect')for l=1,d do k=k+1;j[k]=c[l]c[l]=nil end;d=0 end)if rc==false then print('Error processing raw items: '..err)error(err)end;return j end;return a