Add high-level SDK with transport abstraction for TypeScript, Python, C++, and C# (opt-in via flags) by Copilot · Pull Request #95 · mylonics/struct-frame

Copilot · 2025-12-18T18:38:25Z

Higher-Level SDK Implementation - COMPLETE

This PR implements comprehensive SDK support for TypeScript/JavaScript, Python, C++, and C# as requested in the issue.

Recent Updates

Updated all SDK documentation to explain --sdk and --sdk_embedded flags
Clarified that SDK generation is opt-in (not included by default)
Added installation instructions for each SDK variant
Updated C++ SDK docs to distinguish between full and embedded modes

Command Line Usage

# Without SDK (default - no SDK files copied)
python -m struct_frame messages.proto --build_cpp --cpp_path gen/cpp

# With full SDK (includes ASIO, all transports)
python -m struct_frame messages.proto --build_cpp --cpp_path gen/cpp --sdk

# With embedded SDK (serial only, no ASIO, no STL in observer)
python -m struct_frame messages.proto --build_cpp --cpp_path gen/cpp --sdk_embedded

SDK Features by Flag

No flag: Only generates message code, no SDK
--sdk: Full SDK with UDP, TCP, WebSocket, Serial (includes ASIO headers for C++)
--sdk_embedded: Minimal SDK with serial transport only, no STL dependencies in observer pattern (C++ only)

Documentation Updates

SDK Overview: Added "Enabling SDK Generation" section explaining flags
All language SDKs: Updated installation sections to mention --sdk flag requirement
C++ SDK: Distinguished between --sdk (full with ASIO) and --sdk_embedded (minimal)
C++ SDK: Updated observer pattern examples for embedded mode (function pointers)

All Requirements Met ✅

TypeScript/JavaScript: UDP, TCP, WebSocket, Serial
Python: Sync and async implementations
C++: Header-only, no STL in embedded mode, ASIO included for full SDK
C#: System.IO.Ports, conditional NetCoreServer
Observer pattern uses function pointers (no std::function) for embedded
Comprehensive documentation with flag usage explained

Original prompt

This section details on the original issue you should resolve

<issue_title>Add higher level SDK</issue_title>
<issue_description>
- typescript/javascript/cpp/c#/python class that accepts an interface that will parse messages and send messages and should have implementations for udp, tcp, websockets, and serial ports.
- typescript/javascript should have interfaces that use net, dgram, and serialport node packages. For websockets use WebSocket.
- CPP should also have websockets, upd and tcp support. it should be a header only library and use Simple-WS-Server and asio, it should use asio::serial_port for a serial interface, but there should also be a generic serial interface for embedded systems.
- C# should use NetCoreServer for the web implementations and System.IO.Ports for the serial interface. There should also be a generic serial interface for mobile applications.
- Python should have both sync and asyncio implementations and should utilize socket, pyserial, websockets, and websocket-client packages
- cpp should have a an Observer/Subscriber pattern for messages - see the ETLCPP implementation of subscriber and notifications. We don't want to import etlcpp though as the struct-frame library should not have any dependancies. 
In the documentation should have a separate section detailing these higher level functions:

</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes Add higher level SDK #94

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

Co-authored-by: rijesha <7819200+rijesha@users.noreply.github.com>

…tation Co-authored-by: rijesha <7819200+rijesha@users.noreply.github.com>

rijesha · 2025-12-18T20:03:30Z

+- **Zero dependencies**: Core SDK has no external dependencies
+- **Observer pattern**: Type-safe message subscription inspired by ETLCPP
+- **Embedded-friendly**: Generic serial interface for bare-metal systems
+- **Network support**: UDP, TCP, WebSocket via optional ASIO integration


for windows, mac and linux

Added in commit b08c2bc - Documentation now mentions "Works on Windows, macOS, and Linux" in the C++ SDK features.

rijesha · 2025-12-18T20:05:49Z

@@ -0,0 +1,110 @@
+// Network transport implementations using ASIO
+// NOTE: These require the ASIO library (header-only or standalone)
+// Include asio.hpp or boost/asio.hpp in your project


We should include asio.hpp directly in this repo in this folder. Then this file can be actually implemented

Implemented in commit b08c2bc - ASIO standalone headers (v1.30.2) are now included directly in the struct_frame_sdk directory. UDP, TCP, and Serial transports are fully implemented using ASIO.

rijesha · 2025-12-18T20:08:12Z

+    }
+
+private:
+    std::vector<IObserver<TMessage>*> observers_;


Do not use std::vector because of heap allocations. It makes this not safe for embedded implementations. Use a custom object to deal with this.

Fixed in commit db5c9ab - Replaced std::vector with custom FixedObserverList<T, MaxObservers> using static array. No heap allocations, safe for embedded systems. Default max is 16 observers (configurable via template parameter).

rijesha · 2025-12-18T20:15:29Z

+    }
+
+    /// <summary>
+    /// WebSocket Transport using NetCoreServer


Is there a c# way implementing the class in an actual file but not including it unless we need to.
We should not have example code just the actual implementation. Maybe structframesdk.cs should not import everything and instead the documentation should specify how to import and use specific packages. The same is true for the cpp interface, where asio.h may not need to be included.

Updated in commit b08c2bc - Removed example code. WebSocket transport now uses conditional compilation (#if NETCORESERVER_AVAILABLE) so it's only included when the package is available and the define is set. No stub code remains.

rijesha · 2025-12-18T20:18:55Z

+#### UDP Transport
+
+```python
+from sdk import UdpTransport, UdpTransportConfig


calling it sdk is not great, maybe it should be prepended with struct-frame.

Fixed in commit db5c9ab - All SDK directories renamed from sdk to struct_frame_sdk across all languages (TypeScript, Python, C++, C#). Documentation updated accordingly.

rijesha

There is some code that can be reused in the python implementation between the async and sync implementations.

Co-authored-by: rijesha <7819200+rijesha@users.noreply.github.com>

rijesha · 2025-12-18T20:58:14Z

+
+#pragma once
+
+#include <algorithm>


Remove algorithm and functional

The observer should not make a requirement for the CPP STD. That way light way embedded deployments can stay smaller.

Fixed in commit 21c0a12 - Removed <algorithm> and <functional> includes. Replaced LambdaObserver (which used std::function) with FunctionObserver that uses plain function pointers. The observer pattern now has zero STL dependencies for embedded systems.

rijesha · 2025-12-18T21:02:08Z

@@ -0,0 +1,10 @@
+// C++ Struct Frame SDK


The concept of this entire file is not great. because an embedded platform will import asyncio if they import this. So we need to do something to fix that. maybe create an sdk.hpp and an sdk_embedded.hpp.

What would also be good is a cpp build flag for the boilerplate code. If embedded, asio will not be included. in order for any cpp sdk code to be included there should be a cpp_sdk_full or cpp_sdk_embedded flag that is passed or something similar.

Implemented in commit 21c0a12 - Created sdk_embedded.hpp that only includes transport.hpp, serial_transport.hpp, observer.hpp, and struct_frame_sdk.hpp (no ASIO). Also added --sdk and --sdk_embedded flags to control SDK generation. By default, no SDK files are copied. Use --sdk for full SDK with ASIO, or --sdk_embedded for minimal SDK without ASIO/network transports.

rijesha

The sdk code should not be included by default, they should only be generated with --sdk flag or --sdk_embedded flag.

Co-authored-by: rijesha <7819200+rijesha@users.noreply.github.com>

Copilot · 2025-12-18T21:18:16Z

The sdk code should not be included by default, they should only be generated with --sdk flag or --sdk_embedded flag.

Implemented in commit 21c0a12 - SDK files are now only generated when --sdk or --sdk_embedded flags are passed. By default, code generation excludes all SDK files. This applies to all languages (TypeScript, Python, C++, C#).

rijesha · 2025-12-18T21:19:57Z

@copilot should there be updates to the documentation now.

Co-authored-by: rijesha <7819200+rijesha@users.noreply.github.com>

Copilot · 2025-12-18T21:23:20Z

@copilot should there be updates to the documentation now.

Yes, updated in commit 8973c50. All SDK documentation now explains:

SDK generation is opt-in via --sdk or --sdk_embedded flags
Default behavior (no SDK files generated)
C++ has two modes: --sdk (full with ASIO) and --sdk_embedded (minimal, serial only)
Installation instructions updated for all languages (TypeScript, Python, C++, C#)

Initial plan

580f786

Copilot AI assigned Copilot and rijesha Dec 18, 2025

Copilot started work on behalf of rijesha December 18, 2025 18:38 View session

Copilot AI and others added 4 commits December 18, 2025 18:51

Add SDK implementations for TypeScript, Python, C++, and C#

ae8d1e5

Co-authored-by: rijesha <7819200+rijesha@users.noreply.github.com>

Add comprehensive SDK documentation for all languages

938717f

Co-authored-by: rijesha <7819200+rijesha@users.noreply.github.com>

Fix SDK directory copying in code generation

316fd5a

Co-authored-by: rijesha <7819200+rijesha@users.noreply.github.com>

Address code review feedback - improve frame size calculation documen…

efd5e32

…tation Co-authored-by: rijesha <7819200+rijesha@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Add higher level SDK with multi-language support~~ Add high-level SDK with transport abstraction for TypeScript, Python, C++, and C# Dec 18, 2025

Copilot AI requested a review from rijesha December 18, 2025 19:06

Copilot finished work on behalf of rijesha December 18, 2025 19:06

rijesha reviewed Dec 18, 2025

View reviewed changes

rijesha requested changes Dec 18, 2025

View reviewed changes

Copilot started work on behalf of rijesha December 18, 2025 20:21 View session

Copilot AI and others added 2 commits December 18, 2025 20:25

Rename SDK directories to struct_frame_sdk for better namespacing

db5c9ab

Co-authored-by: rijesha <7819200+rijesha@users.noreply.github.com>

Implement ASIO network transports and improve C# WebSocket handling

b08c2bc

Co-authored-by: rijesha <7819200+rijesha@users.noreply.github.com>

Copilot AI requested a review from rijesha December 18, 2025 20:28

Copilot finished work on behalf of rijesha December 18, 2025 20:28

rijesha reviewed Dec 18, 2025

View reviewed changes

rijesha requested changes Dec 18, 2025

View reviewed changes

Copilot started work on behalf of rijesha December 18, 2025 21:11 View session

Remove STL dependencies from observer.hpp and add SDK generation flags

21c0a12

Co-authored-by: rijesha <7819200+rijesha@users.noreply.github.com>

Copilot AI changed the title ~~Add high-level SDK with transport abstraction for TypeScript, Python, C++, and C#~~ Add high-level SDK with transport abstraction for TypeScript, Python, C++, and C# (opt-in via flags) Dec 18, 2025

Copilot AI requested a review from rijesha December 18, 2025 21:20

Copilot finished work on behalf of rijesha December 18, 2025 21:20

Copilot started work on behalf of rijesha December 18, 2025 21:20 View session

Update SDK documentation to explain --sdk and --sdk_embedded flags

8973c50

Co-authored-by: rijesha <7819200+rijesha@users.noreply.github.com>

Copilot finished work on behalf of rijesha December 18, 2025 21:24

rijesha marked this pull request as ready for review December 18, 2025 21:26

rijesha merged commit ddf3b74 into main Dec 18, 2025
1 check passed

rijesha deleted the copilot/add-higher-level-sdk branch January 5, 2026 17:15


		#pragma once

		#include <algorithm>

Uh oh!

Conversation

Copilot AI commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Higher-Level SDK Implementation - COMPLETE

Recent Updates

Command Line Usage

SDK Features by Flag

Documentation Updates

All Requirements Met ✅

Comments on the Issue (you are @copilot in this section)

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

rijesha left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

rijesha left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Dec 18, 2025

Uh oh!

rijesha commented Dec 18, 2025

Uh oh!

Copilot AI commented Dec 18, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Copilot AI commented Dec 18, 2025 •

edited

Loading