Merge pull request #116 from zevorn/feat/issue-115-script-runtimes

platform: add Python script runtimes

Author: zevorn

.gitmodules

@@ -9,3 +9,8 @@
 [submodule "vendor/lib/freertos-plus-tcp"]
 	path = vendor/lib/freertos-plus-tcp
 	url = https://github.com/FreeRTOS/FreeRTOS-Plus-TCP.git
+[submodule "third_party/rtthread-micropython"]
+	path = third_party/rtthread-micropython
+	url = https://github.com/RT-Thread-packages/micropython.git
+	branch = master
+	ignore = untracked

Makefile

@@ -90,7 +90,10 @@ A9_PLATFORM       := platform/vexpress-a9
 .PHONY: vexpress-a9-qemu
 vexpress-a9-qemu:
 	@if [ ! -f $(MESON_BUILDDIR_A9)/build.ninja ]; then \
-		meson setup $(MESON_BUILDDIR_A9) --cross-file $(CROSS_FILE_A9); \
+		meson setup $(MESON_BUILDDIR_A9) --cross-file $(CROSS_FILE_A9) \
+			-Dtool_script=true; \
+	else \
+		meson configure $(MESON_BUILDDIR_A9) -Dtool_script=true; \
 	fi
 	meson compile -C $(MESON_BUILDDIR_A9)
 	cd $(A9_PLATFORM) && scons -j$$(nproc)
@@ -374,7 +377,10 @@ MESON_BUILDDIR_LINUX := $(BUILD_DIR)/linux
 .PHONY: build-linux
 build-linux:
 	@if [ ! -f $(MESON_BUILDDIR_LINUX)/build.ninja ]; then \
-		meson setup $(MESON_BUILDDIR_LINUX) -Dosal=linux; \
+		meson setup $(MESON_BUILDDIR_LINUX) -Dosal=linux \
+			-Dtool_script=true; \
+	else \
+		meson configure $(MESON_BUILDDIR_LINUX) -Dtool_script=true; \
 	fi
 	meson compile -C $(MESON_BUILDDIR_LINUX)
 	@echo "Output: $(MESON_BUILDDIR_LINUX)/platform/linux/rtclaw"
@@ -526,6 +532,7 @@ test-smoke-esp32s3:
 .PHONY: test-smoke-vexpress
 test-smoke-vexpress: vexpress-a9-qemu
 	$(call _functest,vexpress-a9-qemu,test_boot.py)
+	$(call _functest,vexpress-a9-qemu,test_vexpress_micropython.py)
 
 .PHONY: test-online-esp32c3
 test-online-esp32c3: run-esp32c3-qemu-flash

claw/meson.build

@@ -62,6 +62,10 @@ if get_option('tool_net')
     feature_defs += '-DCONFIG_RTCLAW_TOOL_NET'
     src_files += files('services/tools/net.c')
 endif
+if get_option('tool_script')
+    feature_defs += '-DCONFIG_RTCLAW_TOOL_SCRIPT'
+    src_files += files('services/tools/script.c')
+endif
 if get_option('tool_mouse')
     feature_defs += '-DCONFIG_RTCLAW_TOOL_MOUSE'
     src_files += files('services/tools/mouse.c')

claw/services/tools/script.c

@@ -0,0 +1,141 @@
+/*
+ * Copyright (c) 2026, Chao Liu <chao.liu.zevorn@gmail.com>
+ * SPDX-License-Identifier: MIT
+ *
+ * Script execution tool.
+ */
+
+#include "claw/services/tools/tools.h"
+#include "platform/scripting.h"
+
+#include <stdio.h>
+#include <string.h>
+
+#define SCRIPT_OUTPUT_MAX 1024
+#define SCRIPT_LANGUAGE_MICROPYTHON "micropython"
+
+__attribute__((weak))
+int claw_platform_script_supported(const char *language)
+{
+    (void)language;
+    return 0;
+}
+
+__attribute__((weak))
+int claw_platform_run_script(const char *language, const char *code,
+                             char *output, size_t output_size)
+{
+    (void)language;
+    (void)code;
+    if (output && output_size > 0) {
+        output[0] = '\0';
+    }
+    return -1;
+}
+
+static const char *script_language_from_params(const cJSON *params)
+{
+    const cJSON *language = cJSON_GetObjectItem(params, "language");
+
+    if (language && cJSON_IsString(language)) {
+        return language->valuestring;
+    }
+
+    return SCRIPT_LANGUAGE_MICROPYTHON;
+}
+
+static claw_err_t tool_run_script_validate(struct claw_tool *tool,
+                                           const cJSON *params)
+{
+    const cJSON *code;
+    const cJSON *language;
+
+    (void)tool;
+    if (!params) {
+        return CLAW_ERR_INVALID;
+    }
+
+    code = cJSON_GetObjectItem(params, "code");
+    language = cJSON_GetObjectItem(params, "language");
+
+    if (!code || !cJSON_IsString(code)) {
+        return CLAW_ERR_INVALID;
+    }
+
+    if (language && !cJSON_IsString(language)) {
+        return CLAW_ERR_INVALID;
+    }
+
+    return CLAW_OK;
+}
+
+static claw_err_t tool_run_script_execute(struct claw_tool *tool,
+                                          const cJSON *params,
+                                          cJSON *result)
+{
+    const cJSON *code = cJSON_GetObjectItem(params, "code");
+    const char *language = script_language_from_params(params);
+    char *output;
+
+    (void)tool;
+    output = claw_malloc(SCRIPT_OUTPUT_MAX);
+    if (!output) {
+        cJSON_AddStringToObject(result, "error", "out of memory");
+        return CLAW_OK;
+    }
+    output[0] = '\0';
+
+    if (!claw_platform_script_supported(language)) {
+        char msg[64];
+
+        snprintf(msg, sizeof(msg), "runtime '%s' not supported", language);
+        cJSON_AddStringToObject(result, "error", msg);
+        claw_free(output);
+        return CLAW_OK;
+    }
+
+    if (claw_platform_run_script(language, code->valuestring,
+                                 output, SCRIPT_OUTPUT_MAX) != 0) {
+        cJSON_AddStringToObject(result, "error",
+                                output[0] ? output
+                                          : "script execution failed");
+        claw_free(output);
+        return CLAW_OK;
+    }
+
+    cJSON_AddStringToObject(result, "status", "ok");
+    cJSON_AddStringToObject(result, "language", language);
+    cJSON_AddStringToObject(result, "output", output);
+    if (strlen(output) >= SCRIPT_OUTPUT_MAX - 1) {
+        cJSON_AddBoolToObject(result, "truncated", 1);
+    }
+
+    claw_free(output);
+    return CLAW_OK;
+}
+
+static const char schema_run_script[] =
+    "{\"type\":\"object\","
+    "\"properties\":{"
+    "\"language\":{\"type\":\"string\","
+    "\"description\":\"Scripting runtime. Defaults to micropython.\"},"
+    "\"code\":{\"type\":\"string\","
+    "\"description\":\"Script source code to execute on-device.\"}},"
+    "\"required\":[\"code\"]}";
+
+static const struct claw_tool_ops run_script_ops = {
+    .execute = tool_run_script_execute,
+    .validate_params = tool_run_script_validate,
+};
+
+static struct claw_tool run_script_tool = {
+    .name = "run_script",
+    .description =
+        "Execute a short on-device script and return stdout or "
+        "exception output. RT-Thread uses MicroPython, Linux uses Python.",
+    .input_schema_json = schema_run_script,
+    .ops = &run_script_ops,
+    .flags = CLAW_TOOL_LOCAL_ONLY,
+};
+
+CLAW_TOOL_REGISTER(run_script, &run_script_tool);

include/platform/scripting.h

@@ -0,0 +1,27 @@
+/*
+ * Copyright (c) 2026, Chao Liu <chao.liu.zevorn@gmail.com>
+ * SPDX-License-Identifier: MIT
+ *
+ * Platform hooks for embedded script execution.
+ */
+
+#ifndef PLATFORM_SCRIPTING_H
+#define PLATFORM_SCRIPTING_H
+
+#include <stddef.h>
+
+/*
+ * Return 1 when the given runtime is available on this platform.
+ * Current users pass "micropython".
+ */
+int claw_platform_script_supported(const char *language);
+
+/*
+ * Execute script source with the selected runtime.
+ * Returns 0 on success, -1 on failure.
+ * output receives stdout / exception text when available.
+ */
+int claw_platform_run_script(const char *language, const char *code,
+                             char *output, size_t output_size);
+
+#endif /* PLATFORM_SCRIPTING_H */

meson_options.txt

@@ -24,6 +24,8 @@ option('tool_sched', type: 'boolean', value: true,
     description: 'Enable scheduler tool')
 option('tool_net', type: 'boolean', value: true,
     description: 'Enable network (HTTP) tool')
+option('tool_script', type: 'boolean', value: false,
+    description: 'Enable embedded script execution tool')
 option('tool_mouse', type: 'boolean', value: false,
     description: 'Enable USB HID mouse tools (ESP32-S3 only)')
 option('heartbeat', type: 'boolean', value: false,

platform/linux/board.c

@@ -7,13 +7,68 @@
 
 #include "platform/board.h"
 
+#ifdef CONFIG_RTCLAW_TOOL_SCRIPT
+#include "platform/scripting.h"
+
+#include <stdio.h>
+#include <string.h>
+
+#define PYTHON_CODE_SIZE   256
+#define PYTHON_OUTPUT_SIZE 1024
+
+static void cmd_python(int argc, char **argv)
+{
+    char code[PYTHON_CODE_SIZE];
+    char output[PYTHON_OUTPUT_SIZE];
+    int off = 0;
+
+    if (argc < 2) {
+        claw_printf("Usage: /python <code>\n");
+        return;
+    }
+
+    code[0] = '\0';
+    for (int i = 1; i < argc && off < (int)sizeof(code) - 1; i++) {
+        off += snprintf(code + off, sizeof(code) - off,
+                        "%s%s", i > 1 ? " " : "", argv[i]);
+        if (off >= (int)sizeof(code)) {
+            code[sizeof(code) - 1] = '\0';
+            break;
+        }
+    }
+
+    if (claw_platform_run_script("python", code,
+                                 output, sizeof(output)) != 0) {
+        claw_printf("%s\n",
+                    output[0] ? output : "Python execution failed");
+        return;
+    }
+
+    if (output[0] != '\0') {
+        claw_printf("%s", output);
+        if (output[strlen(output) - 1] != '\n') {
+            claw_printf("\n");
+        }
+    }
+}
+
+static const shell_cmd_t s_linux_commands[] = {
+    SHELL_CMD("/python", cmd_python, "Execute a short Python snippet"),
+};
+#endif
+
 void board_early_init(void)
 {
     /* No hardware init needed on Linux */
 }
 
 const shell_cmd_t *board_platform_commands(int *count)
 {
+#ifdef CONFIG_RTCLAW_TOOL_SCRIPT
+    *count = SHELL_CMD_COUNT(s_linux_commands);
+    return s_linux_commands;
+#else
     *count = 0;
     return NULL;
+#endif
 }

platform/linux/meson.build

@@ -8,24 +8,38 @@ platform_src = files(
     'ota_stub.c',
 )
 
+if get_option('tool_script')
+    platform_src += files('scripting.c')
+endif
+
 thread_dep = dependency('threads')
+platform_c_args = platform_defs
+
+if get_option('tool_script')
+    platform_c_args += '-DCONFIG_RTCLAW_TOOL_SCRIPT'
+endif
 
 rtclaw_exe = executable('rtclaw',
     platform_src,
     include_directories: [claw_inc, claw_root_inc],
-    c_args: platform_defs,
+    c_args: platform_c_args,
     dependencies: [rtclaw_dep, osal_dep, cjson_dep, thread_dep],
     install: false,
 )
 
 # Unit test executable — links ota_stub.c for OTA symbol resolution
 test_main_src = files('../../tests/unit/test_main_linux.c')
 test_incs = include_directories('../../tests/unit')
+test_platform_src = files('ota_stub.c')
+
+if get_option('tool_script')
+    test_platform_src += files('scripting.c')
+endif
 
 rtclaw_test_exe = executable('rtclaw_test',
-    test_main_src + files('ota_stub.c'),
+    test_main_src + test_platform_src,
     include_directories: [claw_inc, claw_root_inc, test_incs],
-    c_args: platform_defs,
+    c_args: platform_c_args,
     link_with: [unittest_lib],
     dependencies: [rtclaw_dep, osal_dep, cjson_dep, thread_dep],
     install: false,