0
# mbed-ls
1

2
mbed-ls is a Python library that detects and lists mbed-enabled devices connected to the host computer. It provides both a command-line interface and Python API for discovering connected development boards, providing detailed information including platform names, mount points, serial ports, target IDs, and DAPLink versions. The library supports multiple output formats, platform mocking capabilities for testing, and retargeting functionality for development workflows.
3

4
## Package Information
5

6
- **Package Name**: mbed-ls
7
- **Language**: Python
8
- **Installation**: `pip install mbed-ls`
9
- **Supported Platforms**: Windows 7+, Linux, macOS (Darwin)
10

11
## Core Imports
12

13
```python
14
import mbed_lstools
15
from mbed_lstools import create
16
```
17

18
For enum constants:
19

20
```python
21
from mbed_lstools.lstools_base import FSInteraction
22
```
23

24
For platform database access:
25

26
```python
27
from mbed_lstools.platform_database import PlatformDatabase, DEFAULT_PLATFORM_DB
28
```
29

30
## Basic Usage
31

32
### Python API
33

34
```python
35
import mbed_lstools
36

37
# Create platform-specific detector instance
38
mbeds = mbed_lstools.create()
39

40
# List all connected devices
41
devices = mbeds.list_mbeds(unique_names=True, read_details_txt=True)
42

43
for device in devices:
44
    print(f"Platform: {device['platform_name']}")
45
    print(f"Mount point: {device['mount_point']}")
46
    print(f"Serial port: {device['serial_port']}")
47
    print(f"Target ID: {device['target_id']}")
48
    print(f"DAPLink version: {device.get('daplink_version', 'unknown')}")
49
    print("---")
50
```
51

52
### Command Line Interface
53

54
```bash
55
# List devices in table format (default)
56
mbedls
57

58
# Simple format without borders/headers
59
mbedls --simple
60

61
# JSON output with detailed information
62
mbedls --json
63

64
# List all supported platforms
65
mbedls --list
66

67
# Mock a platform (temporary rename)
68
mbedls --mock 0240:MY_CUSTOM_PLATFORM
69
```
70

71
## Capabilities
72

73
### Device Detection Factory
74

75
Creates a platform-specific device detection instance that can list and manage connected mbed-enabled devices.
76

77
```python { .api }
78
def create(skip_retarget=False, list_unmounted=False, force_mock=False):
79
    """
80
    Create platform-specific MbedLsTools instance.
81
    
82
    Args:
83
        skip_retarget (bool): Skip retargeting step if True (default: False)
84
        list_unmounted (bool): Include unmounted platforms if True (default: False)
85
        force_mock (bool): Force mock mode if True (default: False)
86
    
87
    Returns:
88
        MbedLsToolsBase: Platform-specific detector instance or None if unsupported
89
    """
90
```
91

92
### Device Listing and Detection
93

94
Lists all detected mbed-enabled devices with configurable detail levels and filtering options.
95

96
```python { .api }
97
def list_mbeds(fs_interaction=FSInteraction.BeforeFilter, filter_function=None, unique_names=False, read_details_txt=False):
98
    """
99
    List all detected mbed-enabled devices.
100
    
101
    Args:
102
        fs_interaction (FSInteraction): Controls filesystem access behavior during detection.
103
            - FSInteraction.BeforeFilter: Access filesystem before filtering (most accurate, default)
104
            - FSInteraction.AfterFilter: Access filesystem after filtering (faster but potentially less accurate)
105
            - FSInteraction.Never: Never access filesystem (fastest but least accurate)
106
        filter_function (callable): Optional function to filter results based on device properties.
107
            Should return True to include device in results. Example: lambda m: m['platform_name'] == 'K64F'
108
        unique_names (bool): Generate unique platform names (e.g., 'K64F[0]', 'K64F[1]') if True
109
        read_details_txt (bool): Read additional device details from DETAILS.TXT file if True
110
    
111
    Returns:
112
        list: List of device dictionaries with device information including platform_name,
113
            mount_point, serial_port, target_id, and additional properties when read_details_txt=True
114
    """
115
```
116

117
### Platform Mocking
118

119
Temporarily substitute platform IDs with custom platform names for testing and development purposes.
120

121
```python { .api }
122
def mock_manufacture_id(mid, platform_name, oper='+'):
123
    """
124
    Mock/substitute platform ID to platform name mapping.
125
    
126
    Args:
127
        mid (str): First 4 characters of target_id to mock
128
        platform_name (str): New platform name to assign
129
        oper (str): '+' to enable mock, '-' to disable mock (default: '+')
130
    """
131
```
132

133
### Platform Database Access
134

135
Retrieves supported platforms and platform database information for different device types.
136

137
```python { .api }
138
def get_supported_platforms(device_type='daplink'):
139
    """
140
    Get supported platforms from database.
141
    
142
    Args:
143
        device_type (str): Device type to query (default: 'daplink')
144
    
145
    Returns:
146
        dict: Dictionary mapping platform IDs to platform names
147
    """
148

149
def list_manufacture_ids():
150
    """
151
    List all known manufacture IDs and platform names.
152
    
153
    Returns:
154
        dict: Platform database information
155
    """
156
```
157

158
### Command Line Interface
159

160
Main entry point for the command-line interface application.
161

162
```python { .api }
163
def mbedls_main():
164
    """
165
    Main entry point for CLI application.
166
    Handles command-line argument parsing and execution.
167
    """
168
```
169

170
### Utility Functions
171

172
Version information and OS support detection utilities.
173

174
```python { .api }
175
def get_version():
176
    """
177
    Get mbed-ls Python module version string.
178
    
179
    Returns:
180
        str: Package version string
181
    """
182

183
def mbed_os_support():
184
    """
185
    Get supported operating system information.
186
    
187
    Returns:
188
        bool: True if OS is supported
189
    """
190

191
def mbed_lstools_os_info():
192
    """
193
    Get current operating system information.
194
    
195
    Returns:
196
        dict: OS information dictionary
197
    """
198
```
199

200
## Types and Enums
201

202
### FSInteraction Enum
203

204
Controls filesystem interaction behavior during device detection.
205

206
```python { .api }
207
from enum import Enum
208

209
class FSInteraction(Enum):
210
    """Controls filesystem access behavior during device detection."""
211
    NEVER = "never"           # No filesystem access (fastest, least accurate)
212
    AfterFilter = "after"     # Filesystem access after filtering
213
    BeforeFilter = "before"   # Filesystem access before filtering (most accurate, default)
214
```
215

216
### Device Data Structure
217

218
Device dictionaries returned by `list_mbeds()` contain these keys:
219

220
```python { .api }
221
DeviceInfo = {
222
    'platform_name': str,           # Platform name (e.g., 'K64F')
223
    'platform_name_unique': str,    # Unique platform name (e.g., 'K64F[0]')
224
    'mount_point': str,            # Device mount point/drive
225
    'serial_port': str,            # Serial port identifier
226
    'target_id': str,              # Unique target identifier
227
    'target_id_mbed_htm': str,     # Target ID from MBED.HTM file
228
    'target_id_usb_id': str,       # Target ID from USB descriptor
229
    'daplink_version': str,        # DAPLink firmware version
230
    'vendor_id': str,              # USB Vendor ID
231
    'product_id': str,             # USB Product ID
232
    # Additional daplink_* properties when read_details_txt=True
233
    'daplink_auto_reset': str,     # Auto reset capability
234
    'daplink_automation_allowed': str, # Automation allowed flag
235
    'daplink_bootloader_version': str, # Bootloader version
236
    'daplink_git_sha': str,        # Git SHA of firmware
237
    'daplink_hic_id': str,         # Hardware interface circuit ID
238
    'daplink_interface_version': str, # Interface version
239
    'daplink_unique_id': str,      # Unique device identifier
240
    'daplink_usb_interfaces': str, # Available USB interfaces
241
}
242
```
243

244
### Platform-Specific Classes
245

246
Base and platform-specific implementation classes.
247

248
```python { .api }
249
class MbedLsToolsBase:
250
    """Base class for all platform implementations."""
251
    def list_mbeds(self, fs_interaction, filter_function, unique_names, read_details_txt): ...
252
    def mock_manufacture_id(self, mid, platform_name, oper): ...
253
    def get_supported_platforms(self, device_type): ...
254
    def list_manufacture_ids(self): ...
255

256
class MbedLsToolsWin7(MbedLsToolsBase):
257
    """Windows 7+ specific implementation."""
258

259
class MbedLsToolsLinuxGeneric(MbedLsToolsBase):
260
    """Linux generic implementation."""
261

262
class MbedLsToolsDarwin(MbedLsToolsBase):
263
    """macOS Darwin implementation."""
264
```
265

266
### Platform Database Classes
267

268
Platform database management for device type mappings.
269

270
```python { .api }
271
class PlatformDatabase:
272
    """Platform database management class for handling multiple database files.
273
    
274
    Represents a union of multiple platform database files with
275
    inter-process synchronization support.
276
    """
277
    def __init__(self, database_files, primary_database=None): ...
278
    def get(self, index, default=None, device_type='daplink', verbose_data=False): ...
279
    def add(self, id, platform_name, permanent=False, device_type='daplink'): ...
280
    def remove(self, id, permanent=False, device_type='daplink', verbose_data=False): ...
281
    def items(self, device_type='daplink'): ...
282
    def all_ids(self, device_type='daplink'): ...
283

284
# Constants
285
DEFAULT_PLATFORM_DB: dict  # Default platform database dictionary with device mappings
286
LOCAL_PLATFORM_DATABASE: str  # Local user-specific platform database file path
287
LOCAL_MOCKS_DATABASE: str     # Local user-specific mocks database file path
288
```
289

290
### Exceptions
291

292
```python { .api }
293
class CompatibleIDsNotFoundException(Exception):
294
    """Raised when compatible IDs cannot be found on Windows.
295
    
296
    This exception is specifically raised on Windows systems when the
297
    device detection process cannot locate compatible device IDs through
298
    the Windows registry or WMI queries.
299
    """
300
```
301

302
## Retargeting Configuration
303

304
mbed-ls supports retargeting through a local `mbedls.json` configuration file:
305

306
```json
307
{
308
    "<target_id>": {
309
        "<key>": "<value>"
310
    }
311
}
312
```
313

314
Example retargeting configuration:
315

316
```json
317
{
318
    "0240000032044e4500257009997b00386781000097969900": {
319
        "serial_port": "COM99",
320
        "platform_name": "CUSTOM_K64F"
321
    }
322
}
323
```
324

325
This configuration file is automatically loaded from the current working directory and overrides returned device information for matching target IDs. Use `skip_retarget=True` or `--skip-retarget` flag to disable this behavior.
326

327
## Error Handling
328

329
The library handles various error conditions:
330

331
- **Unsupported OS**: `create()` returns `None` for unsupported operating systems
332
- **Permission Issues**: Device detection may fail silently if filesystem access is restricted
333
- **Windows Driver Issues**: Windows requires proper mbed serial port drivers
334
- **Mount Issues**: Linux systems may need automounting configured for device detection
335

336
Always check return values and handle `None` results from `create()`:
337

338
```python
339
mbeds = mbed_lstools.create()
340
if mbeds is None:
341
    print("Platform not supported!")
342
    exit(1)
343
```