declare module '@nordicsemiconductor/nrf-device-lib-js' { export interface DeviceTraits { usb?: boolean; nordicUsb?: boolean; nordicDfu?: boolean; seggerUsb?: boolean; jlink?: boolean; serialPorts?: boolean; broken?: boolean; mcuBoot?: boolean; modem?: boolean; } export interface Device { id: number; serialNumber?: string; // undefined in case udev is not installed traits: DeviceTraits; usb?: USB; jlink?: JLink; // non-Nordic devices may not have serialPorts property at all serialPorts?: Array; hwInfo?: HwInfo; dfuTriggerInfo?: DfuTriggerInfo; dfuTriggerVersion?: DfuTriggerVersion; broken?: null | { description: string; url: string; }; } export interface HwInfo { romSize: number; ramSize: number; romPageSize: number; deviceFamily: string; deviceVersion: string; } export interface DfuTriggerVersion { semVer: string; } export interface DfuTriggerInfo { wAddress: number; wVersionMajor: number; wVersionMinor: number; wFirmwareId: number; wFlashSize: number; wFlashPageSize: number; } export interface USB { serialNumber: string; manufacturer: string | null; osDevicePath: string; product: string | null; device: USBDevice; } export interface USBDevice { busNumber: number; address: number; descriptor: USBDeviceDescriptor; configList: USBConfiguration; // todo: check this prop } export interface USBConfiguration { descriptors: USBConfigurationDescriptor[]; interfaceLists: USBInterface[]; length: number; } export interface USBInterface { descriptors: USBInterfaceDescriptor[]; endpointLists: USBEndpoint[]; } export interface USBEndpoint { descriptors?: USBEndpointDescriptor[]; length: number; } export interface USBDeviceDescriptor { bDescriptorType: number; idVendor: number; idProduct: number; bcdDevice: number; } export interface USBConfigurationDescriptor { bDescriptorType: number; } export interface USBInterfaceDescriptor { bDescriptorType: number; bInterfaceClass: number; bInterfaceSubClass: number; bInterfaceProtocol: number; } export interface USBEndpointDescriptor { bDescriptorType: number; } export interface JLink { serialNumber: string; boardVersion: string | null; // can be null for external jLink jlinkObFirmwareVersion: string | null; deviceFamily: string | null; deviceVersion: string | null; // will be null if device is protected } export interface SerialPort { serialNumber: string | null; comName: string | null; manufacturer: string | null; productId: string | null; vendorId: string | null; vcom: number; path: string | null; } export interface HotplugEvent { device_id: number; event_type: HotplugEventType; device?: Device; } // will be present only if "name" == "nrfdl". May be changed export type FeatureClassification = | 'nrf-internal-confidential' | 'nrf-internal' | 'nrf-external-confidential' | 'nrf-external'; export type HotplugEventType = 'NRFDL_DEVICE_EVENT_ARRIVED' | 'NRFDL_DEVICE_EVENT_LEFT'; export type FirmwareStreamType = 'NRFDL_FW_FILE' | 'NRFDL_FW_BUFFER'; export type FirmwareFormat = | 'NRFDL_FW_INTEL_HEX' | 'NRFDL_FW_ELF' | 'NRFDL_FW_SDFU_ZIP' | 'NRFDL_FW_MCUBOOT' | 'NRFDL_FW_MCUBOOT_MULTI_IMAGE' | 'NRFDL_FW_NRF91_MODEM'; export type LogLevel = | 'NRFDL_LOG_TRACE' | 'NRFDL_LOG_DEBUG' | 'NRFDL_LOG_INFO' | 'NRFDL_LOG_WARNING' | 'NRFDL_LOG_ERROR' | 'NRFDL_LOG_CRITICAL' | 'NRFDL_LOG_OFF'; export interface LogEvent { level: LogLevel; message: string; } namespace Progress { export type OperationName = | 'program' | 'core-info' | 'protection-get' | 'protection-set' | 'register-read' | 'fw-read-info' | 'mcu-state-set' | 'fw-read' | 'fw-verify' | 'recover' | 'reset' | 'erase'; export type ProgressTypeName = | 'upload_image_options' | 'check_bootloader' | 'attach_device' | 'download_image' | 'open_device' | 'close_device' | 'upload_image' | 'erase_image' | 'confirm_image' | 'verify_image' | 'read_images' | 'issue_modem_dfu_reset' | 'enter_programming_state' | 'enter_application_state' | 'get_memory_hash' | 'unknown'; export type OperationState = 'begin' | 'progress' | 'end'; export type OperationResult = 'success' | 'fail'; export interface Operation { operationId?: string; name: OperationName; amountOfSteps: number; description: string; operation: ProgressTypeName; progressPercentage: number; duration?: number; result?: OperationResult; message?: string; // not present in some cases step: number; state: OperationState; } export interface CallbackParameters { context: bigint; taskID: bigint; progressJson: Operation; } } // namespace Progress export type MCUState = 'NRFDL_MCU_STATE_APPLICATION' | 'NRFDL_MCU_STATE_PROGRAMMING'; export interface ProgramOptionals { verify?: boolean | null; netCoreUploadDelay?: number | null; // eslint-disable-next-line prettier/prettier } export interface RTTReadResult { rttReadBuffer: Buffer; } export interface RTTWriteResult { rttBytesWritten: number; } namespace FWInfo { export type BootloaderType = | 'NRFDL_BOOTLOADER_TYPE_NONE' | 'NRFDL_BOOTLOADER_TYPE_MCUBOOT' | 'NRFDL_BOOTLOADER_TYPE_SDFU' | 'NRFDL_BOOTLOADER_TYPE_B0' | 'NRFDL_BOOTLOADER_TYPE_UNKNOWN'; // NOTE: broken. Fix is WIP; TODO: check again export type ImageType = | 'NRFDL_IMAGE_TYPE_APPLICATION' | 'NRFDL_IMAGE_TYPE_BOOTLOADER' | 'NRFDL_IMAGE_TYPE_SOFTDEVICE' | 'NRFDL_IMAGE_TYPE_OPERATIVE_SYSTEM' | 'NRFDL_IMAGE_TYPE_GENERIC' | 'NRFDL_IMAGE_TYPE_UNKNOWN'; export type VersionType = | 'NRFDL_VERSION_TYPE_SEMANTIC' | 'NRFDL_VERSION_TYPE_INCREMENTAL' | 'NRFDL_VERSION_TYPE_STRING'; interface SemanticVersion { major: number; minor: number; patch: number; semverPreNumeric?: number; semverPreAlphaNumeric?: number; semverMetadataNumeric?: number; semverMetadataAlphaNumeric?: number; } interface Version { type: VersionType; semantic: null | SemanticVersion; string: null | string; incremental: null | string; } interface ImageLocation { address: number; size: number; } interface Image { imageLocation?: ImageLocation; imageType: ImageType; version: SemanticVersion | string | number; versionFormat: string; } export interface ReadResult { name: 'fw-read-info'; bootloaderType: BootloaderType; imageInfoList: Image[]; serialNumber: string; operationId?: string; } } // namespace FWInfo export interface Error { errorCode: number; message: string; origin: string; } export interface TimeoutConfig { enumerateMs?: number; deviceInterprocessLockSecs?: number; programReattachMs?: number; sdfuTriggerMs?: number; } export type ProtectionStatus = | 'NRFDL_PROTECTION_STATUS_NONE' | 'NRFDL_PROTECTION_STATUS_REGION0' | 'NRFDL_PROTECTION_STATUS_REGION0_REGION1' | 'NRFDL_PROTECTION_STATUS_SECURE_REGIONS' | 'NRFDL_PROTECTION_STATUS_ALL'; export type DeviceFamily = 'NRF51_FAMILY' | 'NRF52_FAMILY' | 'NRF53_FAMILY' | 'NRF91_FAMILY'; export interface GetProtectionStatusResult { name: Progress.JlinkOperationName; // todo: check for non-jlink operations core: DeviceCore; deviceFamily?: DeviceFamily; protectionStatus: ProtectionStatus; serialNumber: string; operationId?: string; } export interface FirmwareReadResult { name: 'fw-read'; // operation name operationId?: string; file?: string; // was data previously buffer?: string; // was data previously serialNumber: string; } export interface SemanticVersion { major: number; minor: number; patch: number; pre: string; metadata?: string; } type SemanticVersionTopLevel = { versionFormat: 'semantic'; version: SemanticVersion; }; type StringVersion = { versionFormat: 'string'; version: string; }; type IncrementalVersion = { versionFormat: 'incremental'; version: number; }; // only for jLink type ExpectedVersion = { version: string; versionFormat: 'string'; }; // TODO: check (w sys team) if other versionFormats are used (or only string is used) type Version = SemanticVersionTopLevel | StringVersion | IncrementalVersion; // same as ModuleVersion, but without plugins property export type ModuleVersionBase = SemanticModuleVersionBase | IncrementalModuleVersionBase | StringModuleVersionBase; export interface SemanticModuleVersionBase { name: string; description?: string; dependencies?: ModuleVersion[]; // expectedVersion?: Version; -- seems this property doesn't exist at all versionFormat: 'semantic'; version: SemanticVersion; } export interface StringModuleVersionBase { name: string; description?: string; dependencies?: ModuleVersion[]; // expectedVersion?: Version; -- seems this property doesn't exist at all versionFormat: 'string'; version: string; } export interface IncrementalModuleVersionBase { name: string; description?: string; dependencies?: ModuleVersion[]; // expectedVersion?: Version; -- seems this property doesn't exist at all versionFormat: 'incremental'; version: number; } export type ModuleVersion = SemanticModuleVersion | StringModuleVersion | IncrementalModuleVersion; export interface IncrementalModuleVersion { // ModuleVersionPlugin plugins?: ModuleVersionBase[]; classification?: FeatureClassification; expectedVersion?: ExpectedVersion; // ModuleVersionBase name: string; description?: string; dependencies?: ModuleVersion[]; // expectedVersion?: Version; - does it exist // Version versionFormat: 'incremental'; version: number; } export interface StringModuleVersion { // ModuleVersionPlugin plugins?: ModuleVersionBase[]; classification?: FeatureClassification; expectedVersion?: ExpectedVersion; // ModuleVersionBase name: string; description?: string; dependencies?: ModuleVersion[]; // expectedVersion?: Version; // Version versionFormat: 'string'; version: string; } export interface SemanticModuleVersion { // ModuleVersionPlugin plugins?: ModuleVersionBase[]; classification?: FeatureClassification; expectedVersion?: ExpectedVersion; // ModuleVersionBase name: string; description?: string; dependencies?: ModuleVersion[]; // expectedVersion?: Version; // Version versionFormat: 'semantic'; version: SemanticVersion; } export type DeviceCore = 'NRFDL_DEVICE_CORE_APPLICATION' | 'NRFDL_DEVICE_CORE_MODEM' | 'NRFDL_DEVICE_CORE_NETWORK'; export type DeviceCoreInfo = { name: 'core-info'; codeAddress: number; codePageSize: number; codeSize: number; // missing property in newer version of the lib core?: DeviceCore; uicrAddress: number; infoPageSize: number; codeRamPresent: boolean; codeRamAddress: number; dataRamAddress: number; operationId?: string; ramSize: number; qspiPresent: boolean; xipAddress: number; xipSize: number; pinResetPin: number; serialNumber: string; }; export type ReadRegisterResult = { name: string; // operation name // type will be exported as schema by device-lib in the future }; export type AvailablePlugin = 'jlink' | 'serialport' | 'sdfu' | 'mcuBoot' | 'broken'; export interface PluginQueryReq { // one of info, operation, device-operations type: string; // type specific value like type: info, value: oneof [list-operations,available-traits] // type: operation, value: oneof [program, reset, ...] // type: device-operations, value: all value: string; } export interface PluginQueryRspArgs { // type schema, array etc. type: string; // type specific value value: string; } export interface PluginQueryRsp { // input arguments if any in?: PluginQueryRspArgs; // output arguments if any out?: PluginQueryRspArgs; } type JLinkPluginOperationsArguments = import('./JLinkPluginOperationsArguments').JLinkPluginOperationsArguments; type SDFUPluginOperationsArguments = import('./SDFUPluginOperationsArguments').SDFUPluginOperationsArguments; type MCUBootPluginOperationsArguments = import('./MCUBootPluginOperationsArguments').MCUBootPluginOperationsArguments; export type Document = | undefined | DeviceCoreInfo // core-info | FWInfo.ReadResult // fw-read-info | GetProtectionStatusResult // protection-get | FirmwareReadResult // fw-read | ReadRegisterResult; // register-read export function deviceControlExecuteOperation( context: bigint, deviceID: number, operation: JLinkPluginOperationsArguments ): Promise; export function deviceControlExecuteOperations( context: bigint, deviceID: number, completeCB: (error?: Error) => void, docCB: (document: Document) => void, progressCB: (progress: Progress.CallbackParameters) => void, // not sure operations: { operations: | JLinkPluginOperationsArguments[] | MCUBootPluginOperationsArguments[] | SDFUPluginOperationsArguments[]; } ): bigint; /** * * @returns Worker ID */ export function deviceControlExecuteOperationWithProgress( context: bigint, deviceID: number, operation: JLinkPluginOperationsArguments | MCUBootPluginOperationsArguments | SDFUPluginOperationsArguments, completeCB: (error?: Error) => void, progressCB: (progress: Progress.CallbackParameters) => void ): bigint; /** * Will throw TypeError if wasn't successful * Will work only for SDFU * * @param workerId */ export function cancelDeviceOperations(workerId: bigint): void; /** * Create a context object internally in the library. * * @returns The ID of the context. */ export function createContext(options?: { plugins_dir: string }): bigint; /** * Release a context object internally in the library. * * @param context - The ID of the context. */ export function releaseContext(context: bigint): void; /** * Get module version list. * * Get the version of all modules within the library. * * @param context - The ID of the context. * * @returns A promise resolving to an array of ModuleVersion objects. */ export function getModuleVersions(context: bigint): Promise>; export function getDeviceCoreInfo(context: bigint, deviceId: number, core?: DeviceCore): Promise; /** * Enumerate the devices connected to the machine. * * @param context - The ID of the context. * @param filter - Optional. Only list device types that are set to true in the filter. * * @returns A promise resolving to an array of Device objects. */ export function enumerate(context: bigint, filter?: DeviceTraits): Promise>; /** * Program the firmware of a given device. * * @param context - The ID of the context. * @param deviceID - The ID of the device. * @param streamType - The stream type for the firmware. Examples: File or data buffer. * @param firmwareFormat - The format of the firmware. Examples: Zip or hex file. If undefined, will be up to device-lib to decide the type. * @param stream - Reference to the stream. Examples: File name or data buffer. * @param completeCB - Function to be called when programming is finished. * @param progressCB - Function to be called to report progress for the programming. * @param programOptionals - Optional. Set optional verify and mcuEndState fields * @param deviceCore - Optional. Core if device is multi-core. * * @returns The ID of the task performing the programming. */ export function firmwareProgram( context: bigint, deviceID: number, streamType: FirmwareStreamType, firmwareFormat?: FirmwareFormat, stream: string | Buffer, completeCB: (error?: Error) => void, progressCB: (progress: Progress.CallbackParameters) => void, programOptionals?: ProgramOptionals | null, deviceCore?: DeviceCore | null ): bigint; /** * Cancel a task performing programming. * * @param taskID - The ID of the task performing programming. */ export function cancelFirmwareProgram(taskID: bigint): void; /** * Erase the firmware of a given device. * * @param context - The ID of the context. * @param deviceID - The ID of the device. * @param deviceCore - Optional. Core if device is multi-core. * * @returns A promise to be called upon success or failure. */ export function firmwareErase(context: bigint, deviceID: number, deviceCore?: DeviceCore | null): Promise; /** * Program the firmware of a given device. * * @param context - The ID of the context. * @param deviceID - The ID of the device. * @param streamType - The stream type for the firmware. Examples: File or data buffer. * @param firmwareFormat - The format of the firmware. Examples: Zip or hex file. * @param completeCB - Function to be called when reading is finished. * @param progressCB - Function to be called to report progress for reading the firmware. * @param fileName - File name to file if stream is file. * @param mcuEndState - Optional. State to be set after reading firmware. * @param deviceCore - Optional. Core if device is multi-core. * * @returns The ID of the task performing the programming. */ export function firmwareRead( context: bigint, deviceID: number, streamType: FirmwareStreamType, firmwareFormat: FirmwareFormat, completeCB: (result: Error | FirmwareReadResult) => void, progressCB: (progress: Progress.CallbackParameters) => void, fileName?: string | null, mcuEndState?: MCUState | null, deviceCore?: DeviceCore | null ): bigint; /** * Set the log level. Logging must be enabled to receive log messages. * * @param context - The ID of the context. * @param logLevel - The granularity of the logging. */ export function setLogLevel(context: bigint, logLevel: LogLevel): void; /** * Start listening for hotplug events. * * @param context - The ID of the context. * @param completeCB - Function to be called when listening process is stopped or fails. * @param eventCB - Function to be called when an event is received. * * @returns The ID of the task listening for events. */ export function startHotplugEvents( context: bigint, completeCB: (err?: Error) => void, eventCB: (event: HotplugEvent) => void ): bigint; /** * Stop listening for hotplug events. * * @param taskID - The ID of the task listening for events. */ export function stopHotplugEvents(taskID: bigint): void; /** * Start listening for log events. * * @param context - The ID of the context. * @param completeCB - Function to be called when listening process is stopped or fails. * @param eventCB - Function to be called when an event is received. * * @returns The ID of the task listening for events. */ export function startLogEvents( context: bigint, completeCB: (err?: Error) => void, eventCB: (event: LogEvent) => void ): bigint; /** * Stop listening for log events. * * @param taskID - The ID of the task listening for events. */ export function stopLogEvents(taskID: bigint): void; /** * Starts the RTT "engine", blocking until started. * * @param context - The ID of the context. * @param deviceID - The ID of the device. * @param timeoutMs - How long to wait for the operation in ms. * @param control_block_address - Optional control block address. */ export function rttStart( context: bigint, deviceID: number, timeoutMs: number, control_block_address?: number ): Promise; /** * Stops the RTT "engine". * * @param context - The ID of the context. * @param deviceID - The ID of the device. */ export function rttStop(context: bigint, deviceID: number): Promise; /** * Read from RTT interface. * * @param context - The ID of the context. * @param deviceID - The ID of the device. * @param channelIndex - The RTT channel index to read from. * @param maxSize - Max number of bytes to read out. */ export function rttRead( context: bigint, deviceID: number, channelIndex: number, maxSize: number ): Promise; /** * Write to RTT interface. * * @param context - The ID of the context. * @param deviceID - The ID of the device. * @param channelIndex - The RTT channel index to write to. * @param buffer - The buffer to be written. */ export function rttWrite( context: bigint, deviceID: number, channelIndex: number, buffer: Buffer ): Promise; /** * Check if RTT is started. * * @param context - The ID of the context. * @param deviceID - The ID of the device. * * @returns True if RTT is started and false if not. */ export function rttIsStarted(context: bigint, deviceID: number): boolean; /** * Read firmware info. * * @param context - The ID of the context. * @param deviceID - The ID of the device. * @param mcuEndState - Optional. Switch to this state after reading. * * @returns True if RTT is started and false if not. */ export function readFwInfo( context: bigint, deviceID: number, mcuEndState?: MCUState | null ): Promise; /** * Recover a device. * * @param context - The ID of the context. * @param deviceID - The ID of the device. * @param deviceCore - Optional. Core if device is multi-core. * * @returns A promise to be called upon success or failure. */ export function deviceControlRecover( context: bigint, deviceID: number, deviceCore?: DeviceCore | null ): Promise; /** * Reset a given device. * * @param context - The ID of the context. * @param deviceID - The ID of the device. * @param deviceCore - Optional. Core if device is multi-core. * * @returns A promise to be called upon success or failure. */ export function deviceControlReset( context: bigint, deviceID: number, deviceCore?: DeviceCore | null ): Promise; /** * Set the given MCU state. * * @param context - The ID of the context. * @param deviceID - The ID of the device. * @param mcuState - MCU state. * * @returns A promise to be called upon success or failure. */ export function deviceControlSetMcuState(context: bigint, deviceID: number, mcuState: MCUState): Promise; /** * Set protection status * * @param context - The ID of the context. * @param deviceID - The ID of the device. * @param status - Protection status to be set. * @param deviceCore - Optional. Core if device is multi-core. * * @returns A promise to be called upon success or failure. */ export function deviceControlSetProtectionStatus( context: bigint, deviceID: number, status: ProtectionStatus, deviceCore?: DeviceCore | null ): Promise; /** * Get protection status. * * @param context - The ID of the context. * @param deviceID - The ID of the device. * @param deviceCore - Optional. Core if device is multi-core. * * @returns A promise to be called upon success or failure. */ export function deviceControlGetProtectionStatus( context: bigint, deviceID: number, deviceCore?: DeviceCore | null ): Promise; /** * Set timeout configuration. * * @param context - The ID of the context. * @param config - Timeout configuration. */ export function setTimeoutConfig(context: bigint, config: TimeoutConfig): void; /** * Set log pattern. * * This will set the given pattern to the log messages. The formatting options * are described here: * https://github.com/gabime/spdlog/wiki/3.-Custom-formatting * * @param context - The ID of the context. * @param pattern - The log pattern. */ export function setLogPattern(context: bigint, pattern: string): void; /** * Read register. * * Read one or more registers from the device. * * @param context - The ID of the context. * @param deviceID - The ID of the device. * @param path - Path of the register(s). * * @returns A promise to be called upon success or failure. */ export function readRegister(context: bigint, deviceID: number, path: string): Promise; /** * Fw verify based on firmware input against firmware in the device * * @param context - The ID of the context. * @param deviceID - The ID of the device. * @param streamType - The stream type for the firmware. Examples: File or data buffer. * @param firmwareFormat - The format of the firmware. Examples: Zip or hex file. * @param stream - Reference to the stream. Examples: File name or data buffer. * @param deviceCore - Optional. Core if device is multi-core. */ export function fwVerify( context: bigint, deviceID: number, streamType: FirmwareStreamType, firmwareFormat: FirmwareFormat, stream: string, deviceCore?: DeviceCore | null ): Promise; /** * Get available plugins * * @param context */ export function availablePlugins(context: bigint): AvailablePlugin[]; /** * Get JSON schema for the plugin * * @param context - The ID of the context * @param plugin - plugin name */ export function getPluginSchema(context: bigint, plugin: AvailablePlugin): string; export function pluginQuery(context: bigint, pluginName: string, query: PluginQueryReq): PluginQueryRsp; }