probe-web / @probe-web/client / index / Session

Class: Session

Defined in: index.ts:591

An attached target: flashing, RTT and semihosting monitoring, embedded-test runs, raw core access through Session.core, and a full debugger through Session.debugger. Get one from Client.attach or openSession.

Properties

Property	Modifier	Type	Description	Defined in
supports	readonly	(path) => boolean	Whether the server implements an endpoint (always true when unknown).	index.ts:598

Methods

targetMetadata()

targetMetadata(): Promise<WireSessionTargetMetadata>;

Defined in: index.ts:609

The attached chip: its name, cores (index and core type) and memory map.

Returns

Promise<WireSessionTargetMetadata>

---

flash()

flash(job, onProgress?): Promise<BootInfo>;

Defined in: index.ts:625

Program an image. Resolves with its BootInfo: pass it to Session.boot, or to Session.monitor to start the firmware and watch its output.

Parameters

Parameter	Type
job	FlashJob
onProgress?	ProgressListener

Returns

Promise<BootInfo>

Example

const bootInfo = await session.flash(
  { image: elfBytes, name: 'app.elf', format: 'elf', options: { verify: true } },
  (e) => { const op = progressOperation(e); if (op) console.log(op); },
);

---

verify()

verify(job, onProgress?): Promise<VerifyResult>;

Defined in: index.ts:632

Compare an image with what is in flash, without writing anything.

Parameters

Parameter	Type
job	FlashJob
onProgress?	ProgressListener

Returns

Promise<VerifyResult>

---

eraseAll()

eraseAll(onProgress?): Promise<void>;

Defined in: index.ts:639

Erase the whole chip.

Parameters

Parameter	Type
onProgress?	ProgressListener

Returns

Promise<void>

---

boot()

boot(bootInfo, core?): Promise<void>;

Defined in: index.ts:644

Start the firmware described by bootInfo (from Session.flash) on core.

Parameters

Parameter	Type	Default value
bootInfo	BootInfo	undefined
core	number	0

Returns

Promise<void>

---

createRttClient()

createRttClient(opts?): Promise<RttClientData>;

Defined in: index.ts:649

Configure RTT before flashing an image that contains a control block, and before monitor.

Parameters

Parameter	Type
opts	{ scanRegion?: ScanRegion; elf?: Uint8Array<ArrayBufferLike>; channels?: RttChannelConfigInput[]; defaults?: RttChannelConfigInput; }
opts.scanRegion?	ScanRegion
opts.elf?	Uint8Array<ArrayBufferLike>
opts.channels?	RttChannelConfigInput[]
opts.defaults?	RttChannelConfigInput

Returns

Promise<RttClientData>

---

clearRttClient()

clearRttClient(): void;

Defined in: index.ts:663

Monitor without RTT from now on (the server stops scanning for a control block).

Returns

void

---

setDefmtElf()

setDefmtElf(elf): boolean;

Defined in: index.ts:671

Provide the ELF whose defmt table decodes Defmt channels. Returns whether the ELF has a defmt table. Call it after Session.createRttClient.

Parameters

Parameter	Type
elf	Uint8Array

Returns

boolean

---

monitor()

monitor(
   mode, 
   onEvent, 
   opts?
): Promise<MonitorExitReason>;

Defined in: index.ts:692

Run until cancelled or the core halts, delivering RTT and semihosting output as MonitorEvents. mode is 'attach' (watch firmware that is already running) or the BootInfo from Session.flash (start it first). Set up RTT with Session.createRttClient beforehand; stop with Session.cancel, which resolves this with 'UserExit'. The catch* options halt (and end the monitor) on reset, hard fault, svc or hlt.

Parameters

Parameter	Type
mode	BootInfo | "attach"
onEvent	(e) => void
opts	{ catchReset?: boolean; catchHardfault?: boolean; catchSvc?: boolean; catchHlt?: boolean; }
opts.catchReset?	boolean
opts.catchHardfault?	boolean
opts.catchSvc?	boolean
opts.catchHlt?	boolean

Returns

Promise<MonitorExitReason>

Example

if (elfHasRtt(elf)) await session.createRttClient({ elf });
const exit = await session.monitor(bootInfo, (e) => {
  if (e.kind === 'text') console.log(e.text);
  else if (e.kind === 'semihosting') console.log(e.data);
});

---

listTests()

listTests(boot, onEvent?): Promise<Tests>;

Defined in: index.ts:713

The tests an embedded-test firmware declares.

The firmware is asked over semihosting, so it has to be on the chip and at its reset vector: boot says how to get it there, exactly as monitor takes it. Console output produced while listing arrives on onEvent.

Parameters

Parameter	Type
boot	BootInfo
onEvent	(e) => void

Returns

Promise<Tests>

---

runTest()

runTest(test, onEvent?): Promise<TestResult>;

Defined in: index.ts:723

Run one of the tests from listTests.

Each run resets the target and runs that test alone, which is what makes a failure attributable — and why running a suite takes one call per test.

Parameters

Parameter	Type
test	Test
onEvent	(e) => void

Returns

Promise<TestResult>

---

rttWrite()

rttWrite(
   channel, 
   data, 
   timeoutMs?
): Promise<number>;

Defined in: index.ts:731

Write to an RTT down channel while Session.monitor runs. Strings are sent as UTF-8. Resolves with the number of bytes written, which can be fewer when the buffer is full.

Parameters

Parameter	Type	Default value
channel	number	undefined
data	string | Uint8Array<ArrayBufferLike>	undefined
timeoutMs	number	1000

Returns

Promise<number>

---

cancel()

cancel(): Promise<void>;

Defined in: index.ts:737

Stop a running monitor.

Returns

Promise<void>

---

core()

core(index?): Core;

Defined in: index.ts:743

Raw access to one core: halt, run, reset, memory and core dumps.

Parameters

Parameter	Type	Default value
index	number	0

Returns

Core

---

debugger()

debugger(options?): Debugger;

Defined in: index.ts:763

A Debugger for one core: run control, breakpoints, stepping, stack traces and variables. Works over both transports, except that disassembly needs probe-rs serve (see Debugger.canDisassemble). Throws with kind: 'unsupported' when the server lacks the debug endpoints.

Parameters

Parameter	Type
options	DebuggerOptions

Returns

Debugger

Example

const dbg = session.debugger();
dbg.addEventListener('stopped', (e) => console.log((e as CustomEvent<StoppedDetail>).detail.reason));
dbg.start();
await dbg.loadDebugInfo(elfBytes, 'app.elf');
await dbg.setSourceBreakpoints('src/main.rs', [{ line: 42 }]);
await dbg.continue();