@microtronics/studio-cli 0.42.0 → 0.44.0

package/CHANGELOG.md

@@ -1,14 +1,29 @@
 # Changelog
 
-## 0.42.0 (2026-01-13)
-
-### Features
-
-* add isIotApp helper function to check IoT app project type ([98ce8a1](https://bitbucket.org/microtronics-core/vscode-studio/commits/98ce8a1358bdd4d2ba1635cd4ef1a3f6e8ec0004))
-* add POST endpoint for addon timeseries data insertion ([ace6880](https://bitbucket.org/microtronics-core/vscode-studio/commits/ace6880f801faefc303a8020c7acf87b06db5709))
-
-### Bug Fixes
-
+## 0.44.0 (2026-01-19)
+
+## 0.43.0 (2026-01-19)
+
+### Features
+
+* add debug option to enable mdnCom logging ([34dfd29](https://bitbucket.org/microtronics-core/vscode-studio/commits/34dfd29cf2f5e6776e31463a85f0484a6907b13b))
+* add support for uploading any amx file to an usb device ([e89f108](https://bitbucket.org/microtronics-core/vscode-studio/commits/e89f1087e22e6c0cc88c8b68bbbcc4f1d813dc4f))
+* add USB device detection and listing functionality ([906e3e1](https://bitbucket.org/microtronics-core/vscode-studio/commits/906e3e12bca647f5ceba8b4196f00d507be163d9))
+* add USB device listing command ([fb16e1a](https://bitbucket.org/microtronics-core/vscode-studio/commits/fb16e1ab0c9a52e38467b664e4b2b6adb135a249)), closes [#close](https://bitbucket.org/microtronics-core/vscode-studio/issues/close)
+
+### Bug Fixes
+
+* ensure proper exit code on successful USB upload ([cc1ae63](https://bitbucket.org/microtronics-core/vscode-studio/commits/cc1ae632669e785017c2afaa689c3750ba22d7fb))
+
+## 0.42.0 (2026-01-13)
+
+### Features
+
+* add isIotApp helper function to check IoT app project type ([98ce8a1](https://bitbucket.org/microtronics-core/vscode-studio/commits/98ce8a1358bdd4d2ba1635cd4ef1a3f6e8ec0004))
+* add POST endpoint for addon timeseries data insertion ([ace6880](https://bitbucket.org/microtronics-core/vscode-studio/commits/ace6880f801faefc303a8020c7acf87b06db5709))
+
+### Bug Fixes
+
 * restrict write access rejection to IoT apps only ([13aa98f](https://bitbucket.org/microtronics-core/vscode-studio/commits/13aa98f261632b576681a894ecb375b7ab5a4b99))
 
 ## 0.41.0 (2026-01-12)

package/README.md

@@ -21,9 +21,130 @@ For a reference on all the available `studio-cli` commands, run `studio-cli --he
 
 ## Requirements
 
-[Node.js](https://nodejs.org/en/) at least `20.x.x`.
+[Node.js](https://nodejs.org/en/) version `22` or higher.
 
 
+## Commands
+
+### install (alias: i)
+Install all dependencies in your project.
+
+```console
+$ studio-cli install [dependency...]
+```
+
+**Options:**
+- `-e, --env <environment>` - CLI target environment (defaults to STUDIO_ENV environment variable)
+- `--token <API-token>` - API Access Token (defaults to STUDIO_TOKEN environment variable)
+
+**Examples:**
+```console
+$ studio-cli install
+$ studio-cli i
+$ studio-cli install dependency-name
+```
+
+### build
+Build the project.
+
+```console
+$ studio-cli build [options]
+```
+
+**Options:**
+- `-p, --part <APM part>` - APM part that should be built
+  - Available parts: `dde`, `dlo`, `pov`, `blo`, `dfiles`
+- `-e, --env <environment>` - CLI target environment
+  - Available environments: `lucky`, `wynni`, `production` (default)
+- `--token <API-token>` - API Access Token
+
+**Manifest Overrides:**
+You can overwrite manifest options using the `--option=value` syntax.
+
+**Examples:**
+```console
+$ studio-cli build
+$ studio-cli build --part dlo
+$ studio-cli build --env wynni
+$ studio-cli build --dlo.mainFile="./dlo/test.dlo"
+```
+
+### publish
+Publish the project to the registry.
+
+```console
+$ studio-cli publish [options]
+```
+
+**Options:**
+- `-ph, --phase <release phase>` - Specify a release phase (default: `release`)
+  - Available phases: `alpha`, `beta`, `rc`, `release`, `stage`, `passive`, `withdrawn`
+- `--allowedBackends <null|*|server.xz;server.yz>` - Specify the allowedBackends deployment for this version
+  - `null` - No restrictions (default)
+  - `*` - All backends allowed
+  - `server.xz;server.yz` - Specific backend servers (semicolon-separated)
+- `-e, --env <environment>` - CLI target environment
+  - Available environments: `lucky`, `wynni`, `production` (default)
+- `--token <API-token>` - API Access Token
+- `-i, --packagePath <path>` - Publish the provided library or app package. Use "*" for autodetection
+
+**Examples:**
+```console
+$ studio-cli publish
+$ studio-cli publish --phase beta
+$ studio-cli publish --allowedBackends "*"
+$ studio-cli publish --packagePath ./my-package.tar.gz --env wynni
+```
+
+### package (alias: pack)
+Package the project.
+
+```console
+$ studio-cli package [options]
+```
+
+**Options:**
+- `-ph, --phase <release phase>` - Specify a release phase (default: `release`)
+  - Available phases: `alpha`, `beta`, `rc`, `release`, `stage`, `passive`, `withdrawn`
+- `-e, --env <environment>` - CLI target environment
+  - Available environments: `lucky`, `wynni`, `production` (default)
+- `--token <API-token>` - API Access Token
+
+**Examples:**
+```console
+$ studio-cli package
+$ studio-cli pack --phase alpha
+$ studio-cli pack --env wynni
+```
+
+### usb
+USB device management commands.
+
+#### usb list
+List available USB devices.
+
+```console
+$ studio-cli usb list
+```
+
+#### usb upload
+Upload an AMX binary to a USB device.
+
+```console
+$ studio-cli usb upload -s <serial> -f <path> [--debug]
+```
+
+**Options:**
+- `-s, --serial <serial>` - Device serial number (16 characters hex) **[required]**
+- `-f, --file <path>` - Path to the AMX file (relative to current directory) **[required]**
+- `--debug` - Enable debug logging
+
+**Example:**
+```console
+$ studio-cli usb upload -s 1234567890ABCDEF -f ./app.amx
+$ studio-cli usb upload -s 1234567890ABCDEF -f ./app.amx --debug
+```
+
 ## Development
 
 Execute commands from the root dir

package/out/main.js

@@ -13,6 +13,7 @@ const update_notifier_1 = __importDefault(require("update-notifier"));
 const api_1 = require("./api");
 const log_1 = require("./log");
 const argumentParser_1 = require("./argumentParser");
+const usb_1 = require("./usb");
 const program = new commander_1.Command();
 const notifier = (0, update_notifier_1.default)({ pkg: package_json_1.default });
 const logger = new log_1.Log.Logger();
@@ -145,6 +146,33 @@ program
     const { env, token } = getDefaultOptions(opts);
     main(command, (0, api_1.pack)(cwd, cliFS_1.cliFS, logger, env, token, opts.phase));
 });
+// USB commands
+const usbCommand = program.command('usb').description('USB device management commands');
+usbCommand
+    .command('list')
+    .description('List available USB devices')
+    .action(async () => {
+    await (0, usb_1.printUsbDevices)(logger);
+    notifier.notify();
+});
+usbCommand
+    .command('upload')
+    .description('Upload an AMX binary to a USB device')
+    .requiredOption('-s, --serial <serial>', 'Device serial number (16 characters hex)')
+    .requiredOption('-f, --file <path>', 'Path to the AMX file (relative to current directory)')
+    .requiredOption('--debug', 'Enable debug logging', false)
+    .action(async (opts) => {
+    const fileUri = vscode_uri_1.Utils.joinPath(cwd, opts.file);
+    const result = await (0, usb_1.uploadToDevice)(opts.serial, fileUri, cliFS_1.cliFS, logger, opts.debug);
+    notifier.notify();
+    if (!result.success) {
+        logger.error(result.message);
+        process.exit(1);
+    }
+    else {
+        process.exit(0);
+    }
+});
 module.exports = function (argv) {
     program.parse(argv);
 };

package/out/usb.js

@@ -0,0 +1,189 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listUsbDevices = listUsbDevices;
+exports.printUsbDevices = printUsbDevices;
+exports.findDeviceBySerialNumber = findDeviceBySerialNumber;
+exports.uploadToDevice = uploadToDevice;
+const usb_1 = require("usb");
+const uto_master_1 = require("uto-master");
+const utoStack_1 = require("uto-master/dist/src/utilities/utoStack");
+// Microtronics vendor ID
+const MICROTRONICS_VENDOR_ID = 0x2544;
+/**
+ * Custom WebUSB instance configured to allow Microtronics devices
+ */
+const customWebUSB = new usb_1.WebUSB({
+    // Bypass checking for authorized devices
+    allowedDevices: [
+        {
+            vendorId: MICROTRONICS_VENDOR_ID
+        }
+    ]
+});
+/**
+ * Lists all available USB devices filtered by Microtronics vendor ID
+ * @returns Promise resolving to an array of USB device information
+ */
+async function listUsbDevices() {
+    const devices = await customWebUSB.getDevices();
+    return devices.map((device) => ({
+        productName: device.productName,
+        serialNumber: device.serialNumber || device.productName?.split(' ').pop(),
+        vendorId: device.vendorId,
+        productId: device.productId
+    }));
+}
+/**
+ * Prints USB device product names using the provided logger
+ * @param logger - The logger instance to use for output
+ */
+async function printUsbDevices(logger) {
+    const devices = await listUsbDevices();
+    if (devices.length === 0) {
+        logger.info('No USB devices found.');
+        return;
+    }
+    logger.info('Available USB devices:');
+    devices.forEach((device, index) => {
+        const name = device.productName ||
+            `Unknown Device (VID: 0x${device.vendorId.toString(16)}, PID: 0x${device.productId.toString(16)})`;
+        const serial = device.serialNumber ? ` [${device.serialNumber}]` : '';
+        logger.log(`  ${index + 1}. ${name}${serial}`);
+    });
+}
+/**
+ * Find a USB device by its serial number
+ * @param serialNumber - The 16-character hex serial number of the device
+ * @returns The USB device or null if not found
+ */
+async function findDeviceBySerialNumber(serialNumber) {
+    const devices = await customWebUSB.getDevices();
+    for (const device of devices) {
+        // Check direct serial number or serial from product name
+        const deviceSerial = device.serialNumber || device.productName?.split(' ').pop();
+        if (deviceSerial?.toLowerCase() === serialNumber.toLowerCase()) {
+            return device;
+        }
+    }
+    return null;
+}
+/**
+ * Upload an AMX binary file to a USB device
+ * @param serialNumber - The serial number of the target device
+ * @param fileUri - The URI to the AMX file
+ * @param fs - The filesystem interface for file operations
+ * @param logger - The logger instance for output
+ * @param debugLog - Enable debug logging
+ * @returns Promise resolving to an UploadResult
+ */
+async function uploadToDevice(serialNumber, fileUri, fs, logger, debugLog = false) {
+    // Check if file exists
+    const fileStat = await fs.stat(fileUri);
+    if (!fileStat) {
+        return {
+            success: false,
+            message: `File not found: ${fileUri.fsPath}`
+        };
+    }
+    // Find the device by serial number
+    logger.info(`Searching for device with serial number: ${serialNumber}`);
+    const device = await findDeviceBySerialNumber(serialNumber);
+    if (!device) {
+        return {
+            success: false,
+            message: `Device not found with serial number: ${serialNumber}`
+        };
+    }
+    logger.info(`Device found: ${device.productName}`);
+    // Read the file contents
+    const fileData = (await fs.readFile(fileUri));
+    // Initialize UTO Master
+    const utoMaster = new uto_master_1.UtoMaster();
+    let deviceConnected = false;
+    try {
+        await utoMaster.init();
+        // Set up UTO transmit callback
+        utoMaster.utoTx(async (data) => {
+            if (device.opened) {
+                await device.transferOut(uto_master_1.USB_CONFIGURATION.utoEndpoint, data);
+            }
+        });
+        if (debugLog) {
+            utoMaster.on('mdnCom', (message) => {
+                logger.log('mdnCom', message);
+            });
+            utoMaster.on('mdnComError', (message) => {
+                logger.log('mdnComError', message);
+            });
+        }
+        // Set up progress reporting
+        let lastProgress = -1;
+        utoMaster.on('installing', (data) => {
+            if (!data) {
+                return;
+            }
+            // /*const progress = Math.round(data.progress);
+            if (data !== lastProgress) {
+                lastProgress = data;
+                logger.info(`Upload progress: ${data}%`);
+            }
+        });
+        // Open device and claim interfaces
+        await device.open();
+        await device.selectConfiguration(uto_master_1.USB_CONFIGURATION.configurationNumber);
+        await device.claimInterface(uto_master_1.USB_CONFIGURATION.utoInterface);
+        deviceConnected = true;
+        logger.info('Device connected, starting upload...');
+        // Start UTO polling for receiving data
+        startUtoPolling(device, utoMaster, () => deviceConnected);
+        await utoMaster.requestDeviceInfo();
+        // Upload the file
+        await utoMaster.sendFile(utoStack_1.UtoFileType.pawn, new Uint8Array(fileData.buffer, fileData.byteOffset, fileData.length));
+        logger.done('Upload completed successfully!');
+        return {
+            success: true,
+            message: 'File uploaded successfully'
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            success: false,
+            message: `Upload failed: ${errorMessage}`
+        };
+    }
+    finally {
+        // Clean up - close device
+        deviceConnected = false;
+        if (device.opened) {
+            try {
+                await device.close().catch();
+            }
+            catch {
+                // Ignore close errors
+            }
+        }
+    }
+}
+/**
+ * Start polling for UTO data from the device
+ * @param device - The USB device
+ * @param utoMaster - The UTO Master instance
+ * @param isConnected - Function that returns connection status
+ */
+async function startUtoPolling(device, utoMaster, isConnected) {
+    while (isConnected()) {
+        try {
+            const result = await device.transferIn(uto_master_1.USB_CONFIGURATION.utoEndpoint, uto_master_1.USB_CONFIGURATION.utoSize);
+            if (result.status === 'ok' && result.data) {
+                const uint8Data = new Uint8Array(result.data.buffer);
+                await utoMaster.utoRx(uint8Data);
+            }
+        }
+        catch {
+            // Connection lost or polling stopped
+            break;
+        }
+    }
+}
+//# sourceMappingURL=usb.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@microtronics/studio-cli",
-	"version": "0.42.0",
+	"version": "0.44.0",
 	"description": "Microtronics Studio CLI Tool",
 	"main": "./out/api.js",
 	"typings": "./dist/studio-cli.d.ts",
@@ -45,6 +45,8 @@
 		"semver": "^7.7.2",
 		"tinytar-fix": "^0.1.1",
 		"update-notifier": "^7.3.1",
+		"usb": "^2.14.0",
+		"uto-master": "bitbucket:microtronics-core/wasm-uto-master",
 		"vscode-uri": "^3.0.8",
 		"yaml": "^2.6.1"
 	},