~ubuntu-branches/ubuntu/feisty/comedilib/feisty

int <link linkend="func-ref-comedi-data-read">comedi_data_read</link>(<link linkend="ref-type-comedi-t">comedi_t</link> * device, unsigned int subdevice, unsigned int channel,

130

unsigned int range, unsigned int aref, <link linkend="ref-type-lsampl-t">lsampl_t</link> * data);

131

</programlisting>

132

function reads one such data value from a &comedi; channel, and puts it in

133

the user-specified <parameter>data</parameter> buffer. The

134

135

int <link linkend="func-ref-comedi-data-write">comedi_data_write</link>(<link linkend="ref-type-comedi-t">comedi_t</link> * device, unsigned int subdevice, unsigned int channel,

136

unsigned int range, unsigned int aref, <link linkend="ref-type-lsampl-t">lsampl_t</link> data);

137

</programlisting>

138

works in the opposite direction. Data values returned by this function

139

are unsigned integers less than, or equal to, the maximum sample value

140

of the channel, which can be determined using the function

141

142

143

</programlisting>

144

Conversion of data values to physical units can be performed by the

145

function

146

147

double <link linkend="func-ref-comedi-to-phys">comedi_to_phys</link>(<link linkend="ref-type-lsampl-t">lsampl_t</link> data, comedi_range * range, <link linkend="ref-type-lsampl-t">lsampl_t</link> maxdata);

148

</programlisting>

149

There are two data structures in these commands that are not fully

150

self-explanatory:

151

152

153

154

<para>

155

156

contains all information that a user program has to know about an

157

<emphasis>open</emphasis> &comedi; device. The programmer doesn't have

158

to fill in this data structure manually: it gets filled in by opening

159

the device.

160

</para>

161

</listitem>

162

163

164

<para>

165

166

<quote>data structure</quote> represents one single sample. On most

167

architectures, it's nothing more than a 32 bits value. Internally,

168

&comedi; does some conversion from raw sample data to

169

<quote>correct</quote> integers. This is called <quote>data

170

munging</quote>.

171

</para>

172

</listitem>

173

174

</itemizedlist>

175

</para>

176

<para>

177

Each single acquisition by, for example,

178

179

180

</function>

181

requires quite some overhead, because all the arguments of the

182

function call are checked. If multiple acquisitions must be done on

183

the same channel, this overhead can be avoided by using a function

184

that can read more than one sample:

185

186

int <link linkend="func-ref-comedi-dio-read">comedi_data_read_n</link>(<link linkend="ref-type-comedi-t">comedi_t</link> *it, unsigned int subdev, unsigned int chan, unsigned int range,

187

unsigned int aref, <link linkend="ref-type-lsampl-t">lsampl_t</link> *data, unsigned int n)

188

</programlisting>

189

The number of samples, <parameter class=function>n</parameter>, is

190

limited by the &comedi; implementation (to a maximum of 100 samples),

191

because the call is blocking.

192

</para>

193

<para>

194

The start of the data acquisition can also be delayed by a specified

195

number of nano-seconds:

196

197

int <link linkend="func-ref-comedi-data-read-delayed">comedi_data_read_delayed</link>(<link linkend="ref-type-comedi-t">comedi_t</link> *it, unsigned int subdev, unsigned int chan, unsigned int range,

198

unsigned int aref, <link linkend="ref-type-lsampl-t">lsampl_t</link> *data, unsigned int nano_sec)

199

</programlisting>

200

All these read and write acquisition functions are implemented on top

201

of the generic <link linkend="instructions">instruction</link>

202

command.

203

</para>

204

205

</section>

206

207

</section>

208

209

210

211

<title>

212

Instructions for multiple acquisitions

213

</title>

214

<para>

215

The <emphasis>instruction</emphasis> is one of the most generic,

216

overloaden and flexible functions in the &comedi; API. It is used to

217

execute a multiple of identical acquisitions on the same channel, but

218

also to perform a

219

220

channel.

221

222

An <emphasis>instruction list</emphasis> is a list of instructions,

223

possibly on different channels. Both instructions and instructions

224

lists are executed <emphasis>synchronously</emphasis>, i.e., while

225

<emphasis role="strong">blocking</emphasis> the calling process.

226

This is one of the limitations of instructions; the other one is that

227

they cannot code an acquisition involving timers or external events.

228

These limits are eliminated by the

229

230

primitive.

231

</para>

232

233

234

235

<title>

236

The instruction data structure

237

</title>

238

<para>

239

All the information needed to execute an instruction is stored in the

240

241

data structure:

242

243

struct <anchor id="insn-data-structure">comedi_insn_struct{

244

<anchor id="insn-data-structure-insn">unsigned int insn; // integer encoding the type of acquisition

245

// (or configuration)

246

unsigned int n; // number of samples

247

248

unsigned int subdev; // subdevice

249

unsigned int <anchor id="insn-data-structure-chanspec"><link linkend="ref-macro-CR-PACK">chanspec</link>; // encoded channel specification

250

unsigned int unused[3];

251

} comedi_insn;

252

</programlisting>

253

Because of the large flexibility of the instruction function, many

254

types of instruction do not need to fill in all fields, or attach

255

different meanings to the same field. But the current implementation

256

of &comedi; requires the

257

258

least one byte long.

259

</para>

260

261

<para>

262

The <link linkend="insn-data-structure-insn">insn</link> flag of the

263

264

determines the type of acquisition executed in the corresponding

265

instruction:

266

267

268

269

<para>

270

INSN_READ: the instruction executes a read on an analog channel.

271

</para>

272

</listitem>

273

274

275

<para>

276

INSN_WRITE: the instruction executes a write on an analog channel.

277

</para>

278

</listitem>

279

280

281

<para>

282

INSN_BITS: indicates that the instruction must

283

read or write values on multiple digital I/O channels.

284

</para>

285

</listitem>

286

287

288

<para>

289

INSN_GTOD: the instruction performs a <quote>Get Time Of Day</quote>

290

acquisition.

291

</para>

292

</listitem>

293

294

295

<para>

296

INSN_WAIT: the instruction blocks for a specified number of

297

nanoseconds.

298

</para>

299

</listitem>

300

301

</itemizedlist>

302

</para>

303

304

</section>

305

306

307

308

<title>

309

Instruction execution

310

</title>

311

<para>

312

Once an instruction data structure has been filled in, the

313

corresponding instruction is executed as follows:

314

315

int <link linkend="func-ref-comedi-do-insn">comedi_do_insn</link>(<link linkend="ref-type-comedi-t">comedi_t</link> *it, <link linkend="ref-type-comedi-insn">comedi_insn</link> * instruction);

316

</programlisting>

317

Many &comedi; instructions are shortcuts that relieve the programmer

318

from explicitly filling in the data structure and calling the

319

320

function.

321

</para>

322

<para>

323

The

324

325

int <link linkend="func-ref-comedi-do-insnlist">comedi_do_insnlist</link><link linkend="ref-type-comedi-t">comedi_t</link> *it, <link linkend="ref-type-comedi-insnlist">comedi_insnlist</link> * list)

326

</programlisting>

327

instruction allows to perform a list of instructions in one function

328

call. The number of instructions in the list is limited in the

329

implementation, because instructions are executed

330

<emphasis>synchronously</emphasis>, i.e., the call blocks until the

331

whole instruction (list) has finished.

332

</para>

333

334

</section>

335

336

</section>

337

338

339

340

<title>

341

Instructions for configuration

342

</title>

343

<para>

344

<xref linkend="instructions"> explains how instructions are used to do

345

<emphasis>acquisition</emphasis> on channels. This section explains

346

how they are used to <emphasis>configure</emphasis> a device.

347

There are various sorts of configurations, and the

348

specific information for each different configuration possibility is

349

to be specified via the

350

351

352

(So, the pointer to a

353

354

is misused as a pointer to an array with board-specific information.)

355

</para>

356

357

<para>

358

Using INSN_CONFIG as the

359

360

361

indicates that the instruction will

362

<emphasis>not perform acquisition</emphasis> on a

363

channel, but will <emphasis>configure</emphasis> that channel.

364

For example, the configuration of digital I/O channels is done as

365

follows. The

366

367

368

data structure, contains the channel to be configured. And

369

370

either COMEDI_INPUT or COMEDI_OUTPUT, depending on the desired

371

direction of the digital I/O lines.

372

On typical devices, multiple channels are grouped together in blocks

373

for determining their direction. And configuring one channel in a

374

block configures the entire block.

375

</para>

376

377

<para>

378

Another example of an INSN_CONFIG instruction is the configuration of

379

the <link linkend="trigother-event">TRIG_OTHER</link> event source.

380

</para>

381

382

</section>

383

384

385

386

<title>

387

Instruction for internal triggering

388

</title>

389

<para>

390

This special instruction has

391

<anchor id="insn-inttrig">INSN_INTTRIG as the

392

393

394

Its execution causes an

395

396

event can, for example, cause the device driver to start a conversion,

397

or to stop an ongoing acquisition. The exact meaning of the triggering

398

depends on the card and its particular driver.

399

</para>

400

<para>

401

The

402

403

INSN_INTTRIG instruction is reserved for future use, and should be set

404

to <quote>0</quote>.

405

</para>

406

407

</section>

408

409

410

411

<title>

412

Commands for streaming acquisition

413

</title>

414

415

<para>

416

The most powerful &comedi; acquisition primitive is the

417

<emphasis>command</emphasis>. It's powerful because, with one single

418

command, the programmer launches:

419

420

421

422

<para>

423

a possibly infinite <emphasis>sequence of acquisitions</emphasis>,

424

</para>

425

</listitem>

426

427

428

<para>

429

accompanied with various <emphasis>callback</emphasis> functionalities

430

(DMA, interrupts, driver-specific callback functions),

431

</para>

432

</listitem>

433

434

435

<para>

436

for <emphasis>any number of channels</emphasis>,

437

</para>

438

</listitem>

439

440

441

<para>

442

with an <emphasis>arbitrary order</emphasis> of channels in each scan

443

(possibly even with repeated channels per scan),

444

</para>

445

</listitem>

446

447

448

<para>

449

and with various scan <emphasis>triggering sources</emphasis>,

450

external (i.e., hardware pulses) as well as internal (i.e., pulses

451

generated on the DAQ card itself, or generated by a

452

453

</para>

454

</listitem>

455

456

</itemizedlist>

457

This command functionality exists in the &comedi; API, because various

458

data acquisition devices have the capability to perform this kind of

459

complex acquisition, driven by either on-board or

460

off-board timers and triggers.

461

</para>

462

463

<para>

464

A command specifies a particular data

465

466

consists of a number of <emphasis>scans</emphasis>, and each scan is

467

comprised of a number of <emphasis>conversions</emphasis>, which

468

usually corresponds to a single A/D or D/A conversion. So, for

469

example, a scan could consist of sampling channels 1, 2 and 3 of a

470

particular device, and this scan should be repeated 1000 times, at

471

intervals of 1 millisecond apart.

472

</para>

473

<para>

474

The command function is complementary to the

475

476

function: each channel in the command's

477

478

should first be configured by an appropriate instruction.

479

</para>

480

481

482

483

<title>

484

Executing a command

485

</title>

486

487

<para>

488

A commands is executed by the following &comedi; function:

489

490

int <link linkend="func-ref-comedi-command">comedi_command</link>(<link linkend="ref-type-comedi-t">comedi_t</link> * device, <link linkend="ref-type-comedi-cmd">comedi_cmd</link> * command);

491

</programlisting>

492

The following sections explain the meaning of the

493

494

Filling in this structure can be quite complicated, and

495

requires good knowledge about the exact functionalities of the DAQ

496

card. So, before launching a command, the application programmer is

497

adviced to check whether this complex command data structure can be

498

successfully parsed. So, the typical sequence for executing a command is

499

to first send the command through

500

501

once or twice. The test will check that the command is valid for the

502

particular device, and often makes some adjustments to the command

503

arguments, which can then be read back by the user to see the actual

504

values used.

505

</para>

506

<para>

507

A &comedi; program can find out on-line what the command capabilities

508

of a specific device are, by means of the

509

510

function.

511

</para>

512

513

</section>

514

515

516

517

<title>

518

The command data structure

519

</title>

520

<para>

521

The command executes according to the information about the requested

522

acquisition, which is stored in the

523

524

<anchor id="command-data-struct">data structure:

525

526

typedef struct comedi_cmd_struct comedi_cmd;

527

528

struct comedi_cmd_struct{

529

unsigned int subdev; // which subdevice to sample

530

unsigned int <anchor id="command-data-struct-flags">flags; // encode some configuration possibilities

531

// of the command execution; e.g.,

532

// whether a callback routine is to be

533

// called at the end of the command

534

535

unsigned int <anchor id="command-data-struct-start-src">start_src; // event to make the acquisition start

536

unsigned int <anchor id="command-data-struct-start-arg">start_arg; // parameters that influence this start

537

538

unsigned int <anchor id="command-data-struct-scan-begin-src">scan_begin_src; // event to make a particular scan start

539

unsigned int <anchor id="command-data-struct-scan-begin-arg">scan_begin_arg; // parameters that influence this start`

540

541

unsigned int <anchor id="command-data-struct-convert-src">convert_src; // event to make a particular conversion start

542

unsigned int <anchor id="command-data-struct-convert-arg">convert_arg; // parameters that influence this start

543

544

unsigned int <anchor id="command-data-struct-scan-end-src">scan_end_src; // event to make a particular scan terminate

545

unsigned int <anchor id="command-data-struct-scan-end-arg">scan_end_arg; // parameters that influence this termination

546

547

unsigned int <anchor id="command-data-struct-stop-src">stop_src; // what make the acquisition terminate

548

unsigned int <anchor id="command-data-struct-stop-arg">stop_arg; // parameters that influence this termination

549

550

unsigned int <anchor id="command-data-struct-chanlist">*chanlist; // pointer to list of channels to be sampled

551

unsigned int <anchor id="command-data-struct-chanlist-len">chanlist_len; // number of channels to be sampled

552

553

sampl_t *<anchor id="command-data-struct-data">data; // address of buffer

554

unsigned int <anchor id="command-data-struct-data-len">data_len; // number of samples to acquire

555

};

556

</programlisting>

557

The start and end of the whole command acquisition sequence, and the

558

start and end of each scan and of each conversion, is triggered by a

559

so-called <emphasis>event</emphasis>. More on these in

560

<xref linkend="comedicmdsources">.

561

</para>

562

563

<para>

564

The <parameter class=function>subdev</parameter> member of the

565

566

the index of the subdevice the command is intended for. The

567

568

function can be useful in discovering the index of your desired subdevice.

569

</para>

570

571

<para>

572

The <link linkend="command-data-struct-chanlist">chanlist</link>

573

member of the

574

575

structure should point to an array whose number of elements is

576

specificed by

577

578

(this will generally be the same as the

579

580

The

581

582

specifies the sequence of channels and gains (and analog references)

583

that should be stepped through for each scan. The elements of the

584

585

initialized by <quote>packing</quote> the channel, range and reference

586

information together with the

587

588

589

</parameter>

590

macro.

591

</para>

592

593

<para>

594

The <link linkend="command-data-struct-data">data</link> and

595

596

members can be safely ignored when issueing commands from a user-space

597

program. They only have meaning when a command is sent from a

598

<emphasis role="strong">kernel</emphasis> module using the

599

<function>kcomedilib</function> interface, in which case they specify

600

the buffer where the driver should write/read its data to/from.

601

</para>

602

603

<para>

604

The final member of the

605

606

607

i.e., bits in a word that can be bitwise-or'd together. The meaning of

608

these bits are explained in a

609

610

</para>

611

612

</section>

613

614

615

616

<title>

617

The command trigger events

618

619

</title>

620

<para>

621

A command is a very versatile acquisition instruction, in the sense

622

that it offers lots of possibilities to let different hardware and

623

software sources determine when acquisitions are started, performed,

624

and stopped. More specifically, the command

625

626

has <emphasis>five</emphasis> types of events: start the

627

628

start a <link linkend="scan">scan</link>, start a

629

630

the acquisition. Each event can be given its own

631

<emphasis><link linkend="source.trigger.anchor">source</link></emphasis>

632

(the <parameter class=function>*_src</parameter> members in the

633

634

structure). And each event source can have a corresponding

635

argument (the <parameter class=function>*_arg</parameter> members of

636

the <link linkend="ref-type-comedi-cmd">comedi_cmd</link> data

637

structure) whose meaning depends on the type of source trigger.

638

For example, to specify an external digital line <quote>3</quote> as a

639

source (in general, <emphasis>any</emphasis> of the five event

640

sources), you would use

641

<parameter>src</parameter>=<link linkend="trig-ext">TRIG_EXT</link> and

642

<parameter>arg</parameter>=3.

643

</para>

644

<para>

645

The following paragraphs discuss in somewhat more detail the trigger

646

event sources(<parameter class=function>*_src</parameter>), and the

647

corresponding arguments (<parameter class=function>*_arg</parameter>).

648

</para>

649

<para>

650

The start of an acquisition is controlled by the

651

652

The available options are:

653

654

655

656

<para>

657

658

TRIG_NOW: the

659

660

event occurs

661

662

nanoseconds after the

663

664

is called. Currently, only

665

666

supported.

667

</para>

668

</listitem>

669

670

671

<para>

672

673

TRIG_FOLLOW: (For an output device.) The

674

675

event occurs when data is written to the buffer.

676

</para>

677

</listitem>

678

679

680

<para>

681

682

TRIG_EXT: the start event occurs when an external trigger signal

683

occurs; e.g., a rising edge of a digital line.

684

685

chooses the particular digital line.

686

</para>

687

</listitem>

688

689

690

<para>

691

692

TRIG_INT: the start event occurs on a &comedi; internal signal, which

693

is typically caused by an

694

695

</para>

696

</listitem>

697

698

</itemizedlist>

699

The start of the beginning of each

700

701

702

The available options are:

703

704

705

706

<para>

707

708

TRIG_TIMER:

709

710

events occur periodically. The time between

711

712

events is

713

714

nanoseconds.

715

</para>

716

</listitem>

717

718

719

<para>

720

721

TRIG_FOLLOW: The

722

723

event occurs immediately after a

724

725

event occurs.

726

</para>

727

</listitem>

728

729

730

<para>

731

732

TRIG_EXT: the

733

734

event occurs when an external trigger signal

735

occurs; e.g., a rising edge of a digital line.

736

737

chooses the particular digital line.

738

</para>

739

</listitem>

740

741

</itemizedlist>

742

The

743

744

used here may not be supported exactly by the device, but it

745

will be adjusted to the nearest supported value by

746

747

</para>

748

<para>

749

The timing between each sample in a

750

751

752

fields:

753

754

755

756

<para>

757

758

759

TRIG_TIMER: the conversion events occur periodically. The time

760

between convert events is

761

762

nanoseconds.

763

</para>

764

</listitem>

765

766

767

<para>

768

769

770

TRIG_EXT: the conversion events occur when an external trigger signal

771

occurs, e.g., a rising edge of a digital line.

772

773

chooses the particular digital line.

774

</para>

775

</listitem>

776

777

778

<para>

779

780

781

TRIG_NOW: All conversion events in a

782

783

</para>

784

</listitem>

785

786

</itemizedlist>

787

The <emphasis>end</emphasis> of each scan is almost always specified

788

using

789

790

the same as the number of channels in the

791

792

could probably find a device that allows something else, but it would

793

be strange.

794

</para>

795

<para>

796

The end of an

797

798

controlled by

799

800

and <link linkend="command-data-struct-stop-arg">stop_arg</link>:

801

802

803

804

<para>

805

806

807

TRIG_COUNT: stop the acquisition after

808

809

scans.

810

</para>

811

</listitem>

812

813

814

<para>

815

816

817

TRIG_NONE: perform continuous acquisition, until stopped using

818

819

</para>

820

<para>

821

Its argument is reserved and should be set to 0.

822

(<quote>Reserved</quote>

823

means that unspecified things could happen if it is set to something

824

else but 0.)

825

</para>

826

</listitem>

827

828

</itemizedlist>

829

There are a couple of less usual or not yet implemented events:

830

831

832

833

<para>

834

835

TRIG_TIME:

836

cause an event to occur at a particular time.

837

</para>

838

<para>

839

(This event source is reserved for future use.)

840

</para>

841

</listitem>

842

843

844

<para>

845

846

TRIG_OTHER: driver specific event trigger.

847

</para>

848

<para>

849

This event can be useful as any of the trigger sources. Its exact

850

meaning is driver specific, because it implements a feature that

851

otherwise does not fit into the generic &comedi; command interface.

852

Configuration of TRIG_OTHER features are done by

853

854

instructions.

855

</para>

856

<para>

857

The argument is reserved and should be set to 0.

858

</para>

859

</listitem>

860

861

</itemizedlist>

862

Not all event sources are applicable to all events. Supported

863

trigger sources for specific events depend significantly on your

864

particular device, and even more on the current state of its device

865

driver. The

866

867

function is useful for determining what trigger sources a subdevice

868

supports.

869

</para>

870

871

</section>

872

873

874

875

<title>

876

The command flags

877

878

</title>

879

880

<para>

881

The

882

883

884

is used to specify some <quote>behaviour</quote> of the acquisitions in

885

a command.

886

The meaning of the field is as follows:

887

888

889

890

<para>

891

892

TRIG_RT: ask the driver to use a

893

<emphasis role="strong">hard real-time</emphasis> interrupt handler.

894

This will reduce latency in handling interrupts from your data

895

aquisition

896

hardware. It can be useful if you are sampling at high frequency, or

897

if your hardware has a small onboard data buffer. You must have a

898

real-time kernel (<ulink url="http://www.rtai.org">RTAI</ulink> or

899

<ulink url="http://fsmlabs.com/community/">RTLinux/Free</ulink>)

900

and must compile &comedi; with real-time support, or this flag will do

901

nothing.

902

</para>

903

</listitem>

904

905

906

<para>

907

908

TRIG_WAKE_EOS:

909

where <quote>EOS</quote> stands for <quote>End of Scan</quote>. Some

910

drivers will change their behaviour when this flag is set, trying to

911

transfer data at the end of every scan (instead of, for example,

912

passing data in chunks whenever the board's hardware data buffer is

913

half full). This flag may degrade a driver's performance at high

914

frequencies, because the end of a scan is, in general, a much more

915

frequent event than the filling up of the data buffer.

916

</para>

917

</listitem>

918

919

920

<para>

921

922

TRIG_ROUND_NEAREST:

923

round to nearest supported timing period, the default.

924

This flag (as well as the following three), indicates how timing

925

arguments should be rounded if the hardware cannot achieve the exact

926

timing requested.

927

</para>

928

</listitem>

929

930

931

<para>

932

933

TRIG_ROUND_DOWN: round period down.

934

</para>

935

</listitem>

936

937

938

<para>

939

940

TRIG_ROUND_UP: round period up.

941

</para>

942

</listitem>

943

944

945

<para>

946

947

TRIG_ROUND_UP_NEXT:

948

this one doesn't do anything, and I don't know what it was intended

949

to do…?

950

</para>

951

</listitem>

952

953

954

<para>

955

956

TRIG_DITHER: enable dithering? Dithering is a software technique to

957

smooth the influence of discretization <quote>noise</quote>.

958

</para>

959

</listitem>

960

961

962

<para>

963

964

TRIG_DEGLITCH: enable deglitching? Another <quote>noise</quote>

965

smoothing technique.

966

</para>

967

</listitem>

968

969

970

<para>

971

972

TRIG_WRITE:

973

write to bidirectional devices. Could be useful, in principle, if

974

someone wrote a driver that supported commands for a digital I/O

975

device that could do either input or output.

976

</para>

977

</listitem>

978

979

980

<para>

981

982

TRIG_BOGUS: do the motions?

983

</para>

984

</listitem>

985

986

987

<para>

988

989

TRIG_CONFIG: perform configuration, not triggering. This is a legacy

990

of the deprecated

991

992

data structure, and has no function at present.

993

</para>

994

</listitem>

995

996

</itemizedlist>

997

</para>

998

999

</section>

1000

1001

1002

<title>

1003

Anti-aliasing

1004

</title>

1005

<para>

1006

If you wish to aquire accurate waveforms, it is vital that you use an

1007

anti-alias filter. An anti-alias filter is a low-pass filter used to

1008

remove all frequencies higher than the Nyquist frequency (half your sampling rate)

1009

from your analog input signal

1010

before you convert it to digital. If you fail to filter your input signal,

1011

any high frequency components in the original analog signal will create

1012

artifacts in your recorded digital waveform that cannot be corrected.

1013

</para>

1014

<para>

1015

For example, suppose you are sampling an analog input channel at a rate of

1016

1000 Hz. If you were to apply a 900 Hz sine wave to the input, you

1017

would find that your

1018

sampling rate is not high enough to faithfully record the 900 Hz input,

1019

since it is above your Nyquist frequency of 500 Hz. Instead, what you

1020

will see in your recorded digital waveform is a 100 Hz sine wave! If you

1021

don't use an anti-alias filter, it is impossible to tell whether the 100

1022

Hz sine wave you see in your digital signal was really produced by a

1023

100 Hz input signal, or a 900 Hz signal aliased to 100 Hz, or a 1100 Hz

1024

signal, etc.

1025

</para>

1026

<para>

1027

In practice, the cutoff frequency for the anti-alias filter is usually

1028

set 10% to 20% below the Nyquist frequency due to fact that real filters

1029

do not have infinitely sharp cutoffs.

1030

</para>

1031

</section>

1032

</section>

1033

1034

1035

1036

<title>

1037

Slowly-varying inputs

1038

</title>

1039

1040

<para>

1041

Sometimes, your input channels change slowly enough that

1042

you are able to average many successive input values to get a

1043

more accurate measurement of the actual value. In general,

1044

the more samples you average, the better your estimate

1045

gets, roughly by a factor of sqrt(number_of_samples).

1046

Obviously, there are limitations to this:

1047

</para>

1048

1049

1050

1051

1052

<para>

1053

you are ultimately limited by <quote>Spurious Free Dynamic

1054

Range</quote>. This SFDR is one of the popular measures to quantify how

1055

much noise a signal carries. If you take a Fourier transform of your

1056

signal, you will see several <quote>peaks</quote> in the transform: one

1057

or more of the fundamental harmonics of the measured signal, and lots

1058

of little <quote>peaks</quote> (called <quote>spurs</quote>) caused by

1059

noise. The SFDR is then the difference between the amplitude of the

1060

fundamental harmonic and of the largest spur (at frequencies below

1061

half of the Nyquist frequency of the DAQ sampler!).

1062

</para>

1063

</listitem>

1064

1065

1066

<para>

1067

you need to have <emphasis>some</emphasis> noise on the input channel,

1068

otherwise you will be averaging the same number <literal>N</literal>

1069

times. (Of course, this only holds if the noise is large enough to

1070

cause at least a one-bit discretization.)

1071

</para>

1072

</listitem>

1073

1074

1075

<para>

1076

the more noise you have, the greater your SFDR, but it

1077

takes many more samples to compensate for the increased

1078

noise.

1079

</para>

1080

</listitem>

1081

1082

1083

<para>

1084

if you feel the need to average samples for, for example, two seconds,

1085

your signal will need to be <emphasis>very</emphasis> slowly-varying,

1086

i.e., not varying more than your target uncertainty for the entire two

1087

seconds.

1088

</para>

1089

</listitem>

1090

1091

</itemizedlist>

1092

1093

<para>

1094

As you might have guessed, the &comedi; library has functions

1095

to help you in your quest to accurately measure slowly varying

1096

inputs:

1097

1098

int <link linkend="func-ref-comedi-sv-init">comedi_sv_init</link>(<link linkend="ref-type-comedi-sv-t">comedi_sv_t</link> * sv, <link linkend="ref-type-comedi-t">comedi_t</link> * device, unsigned int subdevice, unsigned int channel);

1099

</programlisting>

1100

This function initializes the

1101

1102

to do the averaging acquisition:

1103

1104

struct comedi_sv_struct{

1105

1106

unsigned int subdevice;

1107

unsigned int chan;

1108

1109

/* range policy */

1110

int range;

1111

int aref;

1112

1113

/* number of measurements to average (for analog inputs) */

1114

int n;

1115

1116

lsampl_t maxdata;

1117

};

1118

</programlisting>

1119

The actual acquisition is done with:

1120

1121

int <link linkend="func-ref-comedi-sv-measure">comedi_sv_measure</link>(<link linkend="ref-type-comedi-sv-t">comedi_sv_t</link> * sv, double * data);

1122

</programlisting>

1123

The number of samples over which the

1124

<function>comedi_sv_measure()</function> averages is limited by the

1125

implementation (currently the limit is 100 samples).

1126

</para>

1127

1128

<para>

1129

One typical use for this function is the measurement of thermocouple

1130

voltages.

1131

And the &comedi; self-calibration utility also uses these functions.

1132

On some hardware, it is possible to tell it to measure an

1133

internal stable voltage reference, which is typically going

1134

to be very slowly varying; on the kilosecond time scale

1135

or more. So, it is reasonable to measure millions of samples,

1136

to get a very accurate measurement of the A/D converter output

1137

value that corresponds to the voltage reference. Sometimes,

1138

however, this is overkill, since there is no need to

1139

perform a part-per-million calibration to a standard that

1140

is only accurate to a part-per-thousand.

1141

</para>

1142

1143

</section>

1144

1145

1146

<title>

1147

Experimental functionality

1148

</title>

1149

1150

<para>

1151

The following subsections document functionality that has not yet

1152

matured. Most of this functionality has even not been implemented yet

1153

in any single device driver. This information is included here, in

1154

order to stimulate discussion about their API, and to encourage

1155

pioneering implementations.

1156

</para>

1157

1158

1159

<title>

1160

Digital input combining machines

1161

</title>

1162

1163

<para>

1164

(<emphasis role="strong">Status: experimental (i.e., no driver implements

1165

this yet)</emphasis>)

1166

</para>

1167

<para>

1168

When one or several digital inputs are used to modify an output

1169

value, either an accumulator or a single digital line or bit,

1170

a bitfield structure is typically used in the &comedi; interface.

1171

The digital inputs have two properties, <quote>sensitive</quote> inputs

1172

and <quote>modifier</quote> inputs. Edge transitions on sensitive

1173

inputs cause changes in the output signal, whereas modifier inputs

1174

change the effect of edge transitions on sensitive inputs. Note that

1175

inputs can be both modifier inputs and sensitive inputs.

1176

</para>

1177

1178

<para>

1179

For simplification purposes, it is assumed that multiple digital

1180

inputs do not change simultaneously.

1181

</para>

1182

1183

<para>

1184

The combined state of the modifier inputs determine a modifier

1185

state. For each combination of modifier state and sensitive

1186

input, there is a set of bits that determine the effect on the

1187

output value due to positive or negative transitions of the

1188

sensitive input. For each transition direction, there are two

1189

bits defined as follows:

1190

1191

1192

1193

00: transition is ignored.

1194

</member>

1195

1196

1197

01: accumulator is incremented, or output is set.

1198

</member>

1199

1200

1201

10: accumulator is decremented, or output is cleared.

1202

</member>

1203

1204

1205

11: reserved.

1206

</member>

1207

1208

</simplelist>

1209

For example, a simple digital follower is specified by the bit

1210

pattern 01 10, because it sets the output on positive transitions

1211

of the input, and clears the output on negative transitions. A

1212

digital inverter is similarily 10 01. These systems have only

1213

one sensitive input.

1214

</para>

1215

1216

<para>

1217

As another example, a simple up counter, which increments on

1218

positive transitions of one input, is specified by 01 00. This

1219

system has only one sensitive input.

1220

</para>

1221

1222

<para>

1223

When multiple digital inputs are used, the inputs are divided

1224

into two types, inputs which cause changes in the accumulator, and

1225

those that only modify the meaning of transitions on other inputs.

1226

Modifier inputs do not require bitfields, but there needs to be

1227

a bitfield of length 4*(2^(N-1)) for each edge sensitive input,

1228

where N is the total number of inputs. Since N is usually 2 or

1229

3, with only one edge sensitive input, the scaling issues are

1230

not significant.

1231

</para>

1232

1233

</section>

1234

1235

1236

1237

<title>

1238

Analog filtering configuration

1239

</title>

1240

1241

<para>

1242

<emphasis role="strong">(Status: design (i.e., no driver implements

1243

this yet).)</emphasis>

1244

</para>

1245

1246

<para>

1247

The <link linkend="insn-data-structure-insn">insn</link> field of the

1248

1249

has not been assigned yet.

1250

</para>

1251

<para>

1252

The <link linkend="insn-data-structure-chanspec">chanspec</link> field

1253

of the <link linkend="insn-data-structure">instruction data

1254

structure</link> is ignored.

1255

</para>

1256

1257

<para>

1258

Some devices have the capability to add white noise (dithering) to

1259

analog input measurement. This additional noise can then be averaged

1260

out, to get a more accurate measurement of the input signal. It

1261

should not be assumed that channels can be separately configured.

1262

A simple design can use 1 bit to turn this feature on/off.

1263

</para>

1264

1265

<para>

1266

Some devices have the capability of changing the glitch characteristics

1267

of analog output subsytems. The default (off) case should be where

1268

the average settling time is lowest. A simple design can use 1 bit

1269

to turn this feature on/off.

1270

</para>

1271

1272

<para>

1273

Some devices have a configurable analog filters as part of the analog

1274

input stage. A simple design can use 1 bit to enable/disable the

1275

filter. Default is disabled, i.e., the filter being bypassed, or if

1276

the choice is between two filters, the filter with the largest

1277

bandwidth.

1278

</para>

1279

</section>

1280

1281

1282

<title>

1283

Analog Output Waveform Generation

1284

</title>

1285

1286

<para>

1287

<emphasis role="strong">(Status: design (i.e., no driver implements

1288

this yet).)</emphasis>

1289

</para>

1290

<para>

1291

The <link linkend="insn-data-structure-insn">insn</link> field of the

1292

1293

has not been assigned yet.

1294

</para>

1295

<para>

1296

The <link linkend="insn-data-structure-chanspec">chanspec</link> field

1297

of the <link linkend="insn-data-structure">instruction data

1298

structure</link> is ignored.

1299

</para>

1300

1301

<para>

1302

Some devices have the ability to cyclicly loop through samples kept in

1303

an on-board analog output FIFO. This config should allow the user to

1304

enable/disable this mode.

1305

</para>

1306

1307

<para>

1308

This config should allow the user to configure the number of samples

1309

to loop through. It may be necessary to configure the channels used.

1310

</para>

1311

1312

</section>

1313

1314

1315

<title>

1316

Extended Triggering

1317

</title>

1318

<para>

1319

<emphasis role="strong">(Status: alpha.)</emphasis>

1320

</para>

1321

1322

<para>

1323

The <link linkend="insn-data-structure-insn">insn</link> field of the

1324

1325

has not been assigned yet.

1326

</para>

1327

<para>

1328

The <link linkend="insn-data-structure-chanspec">chanspec</link> field

1329

of the <link linkend="insn-data-structure">instruction data

1330

structure</link> is ignored.

1331

</para>

1332

1333

<para>

1334

This section covers common information for all extended

1335

triggering configuration, and doesn't describe a particular

1336

type of extended trigger.

1337

</para>

1338

1339

<para>

1340

Extended triggering is used to configure triggering engines that

1341

do not fit into commands. In a typical programming sequence, the

1342

application will use

1343

1344

to configure an extended trigger, and a

1345

1346

specifying

1347

1348

sources.

1349

</para>

1350

1351

<para>

1352

Extended trigger configuration should be designed in such a way

1353

that the user can probe for valid parameters, similar to how

1354

command testing works. An extended trigger configuration instruction

1355

should not configure the hardware directly, rather, the configuration

1356

should be saved until the subsequent command is issued. This

1357

allows more flexibility for future interface changes.

1358

</para>

1359

1360

<para>

1361

It has not been decided whether the configuration stage should return a

1362

token that is then used as the trigger argument in the command.

1363

Using tokens is one method to satisfy the problem that extended

1364

trigger configurations may have subtle compatiblity issues with

1365

other trigger sources/arguments that can only be determined at

1366

command test time. Passing all stages of a command test should

1367

only be allowed with a properly configured extended trigger.

1368

</para>

1369

1370

<para>

1371

Extended triggers must use

1372

1373

upper 16 bits are reserved and used only for flags that are common to

1374

all extended triggers. The lower 16 bits may be defined by the

1375

particular type of extended trigger.

1376

</para>

1377

1378

<para>

1379

Various types of extended triggers must use

1380

1381

event the extended trigger will be assigned to in the command

1382

structure. The possible values are an OR'd mask of the following:

1383

</para>

1384

1385

1386

1387

<para>

1388

COMEDI_EV_START

1389

</para>

1390

</listitem>

1391

1392

<para>

1393

COMEDI_EV_SCAN_BEGIN

1394

</para>

1395

</listitem>

1396

1397

<para>

1398

COMEDI_EV_CONVERT

1399

</para>

1400

</listitem>

1401

1402

<para>

1403

COMEDI_EV_SCAN_END

1404

</para>

1405

</listitem>

1406

1407

<para>

1408

COMEDI_EV_STOP

1409

</para>

1410

</listitem>

1411

</itemizedlist>

1412

1413

</section>

1414

1415

1416

<title>

1417

Analog Triggering

1418

</title>

1419

<para>

1420

1421

(Status: alpha. The <function>ni_mio_common.c</function> driver

1422

implements this feature.)

1423

</emphasis>

1424

</para>

1425

1426

<para>

1427

The <link linkend="insn-data-structure-insn">insn</link> field of the

1428

1429

has not been assigned yet.

1430

</para>

1431

<para>

1432

The <link linkend="insn-data-structure-chanspec">chanspec</link> field

1433

of the <link linkend="insn-data-structure">instruction data

1434

structure</link> is ignored.

1435

</para>

1436

1437

<para>

1438

The <link linkend="insn-data-structure-data">data</link> field

1439

of the <link linkend="insn-data-structure">instruction data

1440

structure</link> is used as follows:

1441

1442

1443

data[1]: trigger and combining machine configuration.

1444

</member>

1445

1446

data[2]: analog triggering signal chanspec.

1447

</member>

1448

1449

data[3]: primary analog level.

1450

</member>

1451

1452

data[4]: secondary analog level.

1453

</member>

1454

</simplelist>

1455

1456

<para>

1457

Analog triggering is described by a digital combining machine that

1458

has two sensitive digital inputs. The sensitive digital inputs are

1459

generated by configurable analog comparators. The analog comparators

1460

generate a digital 1 when the analog triggering signal is greater

1461

than the comparator level. The digital inputs are not modifier

1462

inputs. Note, however, there is an effective modifier due to the

1463

restriction that the primary analog comparator level must be less

1464

than the secondary analog comparator level.

1465

</para>

1466

1467

<para>

1468

If only one analog comparator signal is used, the combining machine

1469

for the secondary input should be set to ignored, and the secondary

1470

analog level should be set to 0.

1471

</para>

1472

1473

<para>

1474

The interpretation of the chanspec and voltage levels is device

1475

dependent, but should correspond to similar values of the analog

1476

input subdevice, if possible.

1477

</para>

1478

1479

<para>

1480

Notes: Reading range information is not addressed. This makes it

1481

difficult to convert comparator voltages to data values.

1482

</para>

1483

1484

<para>

1485

Possible extensions: A parameter that specifies the necessary time

1486

that the set condition has to be true before the trigger is generated.

1487

A parameter that specifies the necessary time that the reset condition

1488

has to be true before the state machine is reset.

1489

</para>

1490

1491

</section>

1492

1493

1494

<title>

1495

Bitfield Pattern Matching Extended Trigger

1496

</title>

1497

<para>

1498

1499

(Status: design. No driver implements this feature yet.)

1500

</emphasis>

1501

</para>

1502

1503

<para>

1504

The <link linkend="insn-data-structure-insn">insn</link> field of the

1505

1506

has not been assigned yet.

1507

</para>

1508

<para>

1509

The <link linkend="insn-data-structure-chanspec">chanspec</link> field

1510

of the <link linkend="insn-data-structure">instruction data

1511

structure</link> is ignored.

1512

</para>

1513

1514

<para>

1515

The <link linkend="insn-data-structure-data">data</link> field

1516

of the <link linkend="insn-data-structure">instruction data

1517

structure</link> is used as follows:

1518

</para>

1519

1520

1521

data[1]: trigger flags.

1522

</member>

1523

1524

data[2]: mask.

1525

</member>

1526

1527

data[3]: pattern.

1528

</member>

1529

</simplelist>

1530

1531

<para>

1532

The pattern matching trigger issues a trigger when all of a specifed

1533

set of input lines match a specified pattern. If the device allows,

1534

the input lines should correspond to the input lines of a digital input

1535

subdevice, however, this will necessarily be device dependent. Each

1536

possible digital line that can be matched is assigned a bit in the

1537

mask and pattern. A bit set in the mask indicates that the

1538

input line must match the corresponding bit in the pattern.

1539

A bit cleared in the mask indicates that the input line is ignored.

1540

</para>

1541

1542

<para>

1543

Notes: This only allows 32 bits in the pattern/mask, which may be

1544

too few. Devices may support selecting different sets of lines from

1545

which to match a pattern.

1546

</para>

1547

1548

<para>

1549

Discovery: The number of bits can be discovered by setting the mask

1550

to all 1's. The driver must modify this value and return -EAGAIN.

1551

</para>

1552

1553

</section>

1554

1555

1556

<title>

1557

Counter configuration

1558

</title>

1559

<para>

1560

1561

(Status: design. No driver implements this feature yet.)

1562

</emphasis>

1563

</para>

1564

1565

<para>

1566

The <link linkend="insn-data-structure-insn">insn</link> field of the

1567

1568

has not been assigned yet.

1569

</para>

1570

<para>

1571

The <link linkend="insn-data-structure-chanspec">chanspec</link> field

1572

of the <link linkend="insn-data-structure">instruction data

1573

structure</link> is used to specify which counter to use. (I.e., the

1574

counter is a &comedi; channel.)

1575

</para>

1576

1577

<para>

1578

The <link linkend="insn-data-structure-data">data</link> field

1579

of the <link linkend="insn-data-structure">instruction data

1580

structure</link> is used as follows:

1581

</para>

1582

1583

1584

data[1]: trigger configuration.

1585

</member>

1586

1587

data[2]: primary input chanspec.

1588

</member>

1589

1590

data[3]: primary combining machine configuration.

1591

</member>

1592

1593

data[4]: secondary input chanspec.

1594

</member>

1595

1596

data[5]: secondary combining machine configuration.

1597

</member>

1598

1599

data[6]: latch configuration.

1600

</member>

1601

</simplelist>

1602

1603

<para>

1604

Note that this configuration is only useful if the counting has to be

1605

done in <emphasis>software</emphasis>. Many cards offer configurable

1606

counters in hardware; e.g., general purpose timer cards can be

1607

configured to act as pulse generators, frequency counters, timers,

1608

encoders, etc.

1609

</para>

1610

<para>

1611

Counters can be operated either in synchronous mode (using

1612

1613

or asynchronous mode (using

1614

1615

input subdevices.

1616

The input signal for both modes is the accumulator.

1617

Commands on counter subdevices are almost always specified using

1618

1619

= <link linkend="trigother-event">TRIG_OTHER</link>, with the

1620

counter configuration also serving as the extended configuration for

1621

the scan begin source.

1622

</para>

1623

1624

<para>

1625

Counters are made up of an accumulator and a combining machine that

1626

determines when the accumulator should be incremented or decremented

1627

based on the values of the input signals. The combining machine

1628

optionally determines when the accumulator should be latched and

1629

put into a buffer. This feature is used in asynchronous mode.

1630

</para>

1631

1632

<para>

1633

Note: How to access multiple pieces of data acquired at each event?

1634

</para>

1635

1636

</section>

1637

1638

1639

<title>

1640

One source plus auxiliary counter configuration

1641

</title>

1642

<para>

1643

1644

(Status: design. No driver implements this feature yet.)

1645

</emphasis>

1646

</para>

1647

1648

<para>

1649

The <link linkend="insn-data-structure-insn">insn</link> field of the

1650

1651

has not been assigned yet.

1652

</para>

1653

<para>

1654

The <link linkend="insn-data-structure-chanspec">chanspec</link> field

1655

of the <link linkend="insn-data-structure">instruction data

1656

structure</link> is used to …

1657

</para>

1658

1659

<para>

1660

The <link linkend="insn-data-structure-data">data</link> field

1661

of the <link linkend="insn-data-structure">instruction data

1662

structure</link> is used as follows:

1663

</para>

1664

1665

<para>

1666

1667

1668

data[1]: is flags, including the flags for the command triggering

1669

configuration. If a command is not subsequently issued on the

1670

subdevice, the command triggering portion of the flags are ignored.

1671

</member>

1672

1673

data[2]: determines the mode of operation. The mode of operation

1674

is actually a bitfield that encodes what to do for various

1675

transitions of the source signals.

1676

</member>

1677

1678

1679

data[3], data[4]: determine the primary source for the counter,

1680

similar to the

1681

1682

1683

used in the

1684

1685

</member>

1686

1687

</simplelist>

1688

</para>

1689

1690

<para>

1691

Notes: How to specify which events cause a latch and push, and what

1692

should get latched?

1693

</para>

1694

1695

</section>

1696

1697

</section>

1698

1699

</section>

1700

Older »