Add binary upload example

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: Bucknalla

examples/binary-mode/binary_upload_example.py

@@ -0,0 +1,102 @@
+"""note-python binary upload example.
+
+This example uploads binary data to a Notehub proxy route using the
+high-speed chunked upload mechanism. The data is staged through the
+Notecard's binary buffer and sent to Notehub via web.post.
+
+Before running this example:
+1. Create a Proxy Route in your Notehub project (e.g. pointing to
+   https://httpbin.org/post or your own endpoint).
+2. Set PRODUCT_UID below to your Notehub product UID.
+3. Set ROUTE_ALIAS to the alias of your proxy route.
+
+Supports MicroPython, CircuitPython, and Raspberry Pi (Linux).
+"""
+import sys
+
+
+PRODUCT_UID = 'com.your-company.your-project'
+ROUTE_ALIAS = 'my-upload-route'
+USE_UART = True
+
+
+def on_progress(info):
+    """Print upload progress after each chunk."""
+    print(f'  Chunk {info["chunk"]}/{info["total_chunks"]} '
+          f'- {info["percent_complete"]:.1f}% '
+          f'- {info["avg_bytes_per_sec"]:.0f} B/s '
+          f'- ETA {info["eta_secs"]:.1f}s')
+
+
+def run_example():
+    """Connect to Notecard and upload binary data to Notehub."""
+    biggest_notecard_response = 400
+
+    if sys.implementation.name == 'micropython':
+        from machine import UART
+        from machine import I2C
+        from machine import Pin
+        import board
+
+        if USE_UART:
+            port = UART(board.UART, 9600)
+            port.init(9600, bits=8, parity=None, stop=1,
+                      timeout=3000, timeout_char=100,
+                      rxbuf=biggest_notecard_response)
+        else:
+            port = I2C(board.I2C_ID, scl=Pin(board.SCL), sda=Pin(board.SDA))
+    elif sys.implementation.name == 'circuitpython':
+        import busio
+        import board
+
+        if USE_UART:
+            port = busio.UART(board.TX, board.RX, baudrate=9600,
+                              receiver_buffer_size=biggest_notecard_response)
+        else:
+            port = busio.I2C(board.SCL, board.SDA)
+    else:
+        import os
+
+        sys.path.insert(0, os.path.abspath(
+                        os.path.join(os.path.dirname(__file__), '..', '..')))
+
+        from periphery import I2C
+        import serial
+
+        if USE_UART:
+            port = serial.Serial('/dev/ttyACM0', 9600)
+        else:
+            port = I2C('/dev/i2c-1')
+
+    import notecard
+    from notecard import hub
+    from notecard.upload import upload
+
+    if USE_UART:
+        card = notecard.OpenSerial(port, debug=True)
+    else:
+        card = notecard.OpenI2C(port, 0, 0, debug=True)
+
+    # Connect the Notecard to Notehub.
+    hub.set(card, product=PRODUCT_UID, mode='continuous')
+
+    # Generate some test data (1 KB of a repeating pattern).
+    data = bytearray(range(256)) * 4
+    print(f'Uploading {len(data)} bytes to route "{ROUTE_ALIAS}"...')
+
+    result = upload(
+        card,
+        data,
+        route=ROUTE_ALIAS,
+        label='test_data.bin',
+        progress_cb=on_progress,
+    )
+
+    print(f'Upload complete: {result["bytes_uploaded"]} bytes '
+          f'in {result["chunks"]} chunks, '
+          f'{result["duration_secs"]:.1f}s '
+          f'({result["bytes_per_sec"]:.0f} B/s)')
+
+
+if __name__ == '__main__':
+    run_example()