20000730_CLINIC_NMRA-00 Computer Interface App.pdf

KAM * Matt Katzer 

San Jose, Calif. 

NMRA 2000 

Copyright 2000 KAM Industries 

all rights reserved. 

*KAM Industries is a division of 

KAMIND Associates, Inc. 

Hands on training in using Computer Dispatcher® pro software 

Page 1 

KAM 

TM

KAM * CTC view of KAMville railroad 

Matt Katzer 







Page 2 

KAM 

TM

KAM * Top view of KAMville RR 

Matt Katzer 







Page 3 

KAM 

TM

KAM * Where we started with the layout 

Matt Katzer 







Page 4 

KAM 

TM

KAM * Prep for the Computer Dispatcher® clinic 

Matt Katzer 







Page 5 

KAM 

TM

KAM * The cows have arrived to the Computer Dispatcher® pro clinic 

Matt Katzer 







Page 6 

KAM 

TM

KAM * Matt Katzer 

KAM Industries 

Portland, Or. 

Matt Katzer 







Computer Interface Application 

Programming for DCC 

Page 7 

KAM 

TM

KAM * Agenda 

• History 

• Train Server ® Interface architecture 

– Key concepts and terms 

– Execution model 

• How the API works 

– Logical devices 

– Decoder structure 

– Command structure 

• API summary 

• Using the API in Visual Basic/MS Java or C/C++ 

• Questions/Answers 

Clinic slides will be posted on KAMs website 

http://www.kamind.com by 8/30/200 

Matt Katzer 







Page 8 

KAM 

TM

KAM * Why are you here 

• Clinic will focus on API architecture 

– we will talk application programming 

– programming languages 

– implementation example programs (C++ and VB) 

• What are your expectations 

Matt Katzer 







• Clinic will review the proposed API architecture 

Page 9 

KAM 

TM

KAM * History of the API... 

• Train Server® API was developed to 

address an internal need at KAM 

– KAM needed a way to control schedules/costs 

» non standard mfg computer interfaces are costly to support 

» every command station vendor had their own architecture 

– Standardization was needed to address product 

development 

» API was required so KAM could decouple the GUI (client) 

» Required a full network backbone 

» Must support Windows 9x/M, NT 4.0 Win 2000 and 

Microsoft.Net 

» KAM created a standard interface for a product family 

Matt Katzer 







Page 10 

KAM 

TM

KAM * History (cont.) 

• KAM needed an API that was language friendly 

– Need flexibility to implement MS J++ (Java)/Sun Java 

– Visual Basic/Visual Basic for Applications (Excel, Word access..) 

– Needed support for C/C++ and C# 

– Needed support for our web servers via distributed Common 

Object Model (DCOM) and XML 

• Our next generation application Computer 

Dispatcher® software was an object driven model 

which required integrated network support. 

– We needed an API that delivered functionality and implementation 

performance. 

– Required COM and CORBA standards 

– Required source level compatibility at the minimum 

– API must support different operating systems and processors 

Matt Katzer 







Page 11 

KAM 

TM

KAM * KAM’s family of products 

– Engine Commander (manual control) 

– Layout Commander (automatic control) 

– Computer Dispatcher Pro (dispatching software) 

– Allows multiple applications to run 

– Share data model (either locally or distributed) 

– Implemented with KAM’s patent technology 

Matt Katzer 







• KAM has three product family’s supporting 

the API 

• KAM’s implementation is called Train Server 

Page 12 

KAM 

TM

KAM * Engine Commander® 

• Built on a modular philosophy 

– Implements all of the API’s 

– Simple interface, but uses abstraction to reduce complexity of task 

– An accessory through switches.. 

– A throttle run trains.. 

– A sensor displays state 

• All applications can run at the same time 

Matt Katzer 







Page 13 

KAM 

TM

KAM * Layout Commander® Lite 

CTC panel view in Layout Commander® 

with automatic block operation 

Matt Katzer 







• Development of a non prototype application 

for the consumer…. 

Switches and sensors 

Computer Dispatcher® Lite 

active elements 

Page 14 

KAM 

TM

KAM * N W 2 1 

ENT PO SD LPO LIN LIN 

A 

21 12 

1N 

CTC Panel view in Computer Dispatcher® 

Matt Katzer 







Computer Dispatcher® Pro 1 

• KAM needed to build an infrastructure so we 

could support prototype operation…. 

1. Available in Q1’ 20000 

ABS 

2N 1S 

ABS 

ABS 

21 

Page 15 

Active Objects 

B MC ABS 2S 

491 

Computer Dispatcher® 

model view of an active element 

with full Entry/Exit (route) control 

KAM 

TM

KAM * Agenda 

• History 

• Train Server ® Interface architecture 




– Logical Devices 

– Decoder Structure 





Matt Katzer 







Page 16 

KAM 

TM

KAM * NMRA Application S/W 

Architecture Model 

• There are four parts to the NMRA DCC 

software architecture model 

Katzer/Rice Draft Protocol Specification (7/9 

no activity 

Protocol Driver 

O/S Device Driver 

Application Programming Interface 

Object Architecture 

KAM Industries submission (7/98) 

updated 6/99 

specification located on Http://www.kamind.com 

Rosa Proposal by Tannersoft (7/97) 

Matt Katzer 







Page 17 

KAM 

TM

KAM * API Architecture 

• API is a combination of a property/method 

model; with an execution framework 

– Objects are not passed in the API; states are passed 

– The state model reduces overhead on clients and improves 

the ability to port the API to different architecture 

(marshalling is expensive in software) 

– States are set; and execution is passed 

Train 

» DccEngSetFunction(…..) 

Set something(,,) 

» DccEngGetSpeed(…) 

» DccCommand(ObjectId) 

Get something(,,) 

• The API was designed to support prototype 

and non prototype operations 

Matt Katzer 







Page 18 

KAM 

TM

KAM * Agenda 

• History 

• Train Server ® interface architecture 










Matt Katzer 







Page 19 

KAM 

TM

KAM * Architecture 

• API is built on the following concepts 

– Devices are logical devices. There is a mapping between 

logical to physical 

» DccPortGetMaxLogPorts(lMaxLogical) 

» PortGetMaxPhysical(lMaxPhysical, lMaxSerial, lMaxParallel) 

» DccPortGetName(iComPort, strComPort) 

» DccMiscGetControllerName(iController, strCntrl) 

» DccPortSetConfig(iLogicalPort, 0, iPortRetrans, 0) 

» DccPortSetMapController(iLogicalPort, iController, iPhysicalPort) 

– Abstraction for the client was the key. 

» Client does not need configuration ability 

» Client only needs to know how map a logical to a physical device 

» The configuration extension was added to accommodate new 

manufactures equipment using a standard driver. 

Matt Katzer 







Page 20 

KAM 

TM

KAM * Demo 

• Command station support 

• 26 different command stations supported 

Matt Katzer 







Page 21 

KAM 

TM

KAM * DCC Object (Cookie) 

Matt Katzer 







• DCC addresses are integrated in an object 

– Objects have a reference and can be translated 

– The object must be complete enough to use the API with as 

little information as possible 

– All information to control accessories or locomotives require 

and object as a reference 

» This allows developers to implement the sever as an 

object store independent of the operating system 

architecture. 

» The objects then become a “DccCookie”. 

• DccCookie encapsulate programming ports, command 

ports, decoder class and DCC addresss 

• The DCC cookie becomes the reference token for system 

calls and can easily be validated 

Page 22 

KAM 

TM

KAM * Architecture (cont.) 

Matt Katzer 







• Abstraction also extends to decoders 

– we needed a model that allowed flexibility and growth 

» Decoder classes were created to group decoders. 

» Each decoder class supports multiple decoder models 

• Classes are “Loco”, “Switch”,”Sensor” 

• Models are DH84, K87, LS110, Chub Detector1 

» A set of decoder management fucntions were added to 

support applciaiton development 

• DccDecoderGetMaxModels(…) 

• DccDecoderGetModelName(…) 

• DccDecoderGetMaxAddress(…) 

• DccDecoderGetMfgName(…) 

• DccDecoderGetPowerMode(…) 

• DccDecoderGetModelFacility(…) 

• DccDecoderSetModelToObject( …) 

– DccObjects are mapped to master models 

Page 23 

KAM 

TM

KAM * Demo 

• Decoder support and logical devices 

• 22 master decoder models supported 

– Grouped by loco, sensors and switches 

– DB store can be updated from web servers 

Matt Katzer 







Page 24 

KAM 

TM

KAM * Agenda 

• History 











Matt Katzer 







Page 25 

KAM 

TM

KAM * API command summary 

• API Command classes 

– CV 

– Engine 

– Consist 

These are the major classes of 

– Accessory 

commands needed in most DCC 

– Command 

software applications. Clients are 

– Programming 

implemented for: 

– Communications 

– Command 

•Engine Commander® client, 

•Classic Panel® client 

– Decoder 

•Layout Commander® client 

– Cab 

•Computer Dispatcher® Pro software 

– Dispatcher operation 

– Block definitions 

Matt Katzer 







Page 26 

KAM 

TM

KAM * Demo 

• API supported in KAMs Train Server® 

• 119 API’s defined! 

Matt Katzer 







Page 27 

KAM 

TM

KAM * Agenda 

• History 











Matt Katzer 







Page 28 

KAM 

TM

KAM * • Lets look at how you program it 

Matt Katzer 







Demo: Visual Basic Throttle 

• How is this Visual Basic application built 

Page 29 

KAM 

TM

KAM * Visual Basic 6 

• First step is to add the object reference 

This is the key for all 

programming 

languages 

We crete an object 

reference 

Matt Katzer 







Page 30 

KAM 

TM

KAM * Visual Basic 5/6 (cont.) 

• next, 

– Write the subroutine to control the loco 

Matt Katzer 







Page 31 

KAM 

TM

KAM * C++ Example 

Matt Katzer 







Page 32 

KAM 

TM

KAM * Lets look at a C++ model 

// Identify the interface of the object that we want to use... 

MULTI_QI qi = {&IID_IEngComIfc, NULL, 0}; 

hr = CoCreateInstanceEx(CLSID_EngComIfc, NULL, 

CLSCTX_LOCAL_SERVER | CLSCTX_REMOTE_SERVER, 

pServerInfo, 1, &qi); 

// add the security call at this point for compatibility for DCOM objects 

//CoInitializeSecurity 

This 

// Now make the com conenction for the interface 

This is is the the key key for for all all 

if (SUCCEEDED(qi.hr)) 

programming 

programming 

{ 

languages languages 

// Now get the remote TrainTools interface 

We 

short sError; 

We crete crete an an object object 

m_pEngIfc = (IEngComIfc*)qi.pItf; 

reference reference 

GetVersion(&m_csIfcVersion ); 

m_pEngIfc->DccPortGetMaxLogPorts(&m_iMaxLogicalPorts, &sError); 

m_pEngIfc->DccPortGetMaxPhysical(&m_iMaxPhysicalPorts, &m_iMaxSerialPorts, &m_iMaxParallelPorts, &sError ); 

m_pEngIfc->DccMiscMaxControllerID(&m_iMaxControlerId, &sError); 

Looks just like VB or Java, that is part of the design 

Matt Katzer 







Page 33 

KAM 

TM

KAM * C++ cont. 

/* 

* NAME 

* DecoderGetModelFromCookie() - Get controller facilities. 

* RETURN VALUE 

* iModel - Decoder model ID. 

* 

* DESCRIPTION 

* DecoderGetModelFromCookie() gets the decoder model ID. 

*/ 

int TInterfaceDevice::DecoderGetModelFromCookie(long lCookie ) const 

{ 

TRACE( "TInterfaceDevice::DecoderGetModelFromCookie( 0x%08lx ) - Entering\n",lCookie ); 

short iError; 

int iLogCmdPort, iLogProgPort, iDCCAddr, iDecoderClass, iDecoderModel; 

m_pEngIfc->DccDecoderTranslate(lCookie, &iLogCmdPort, &iLogProgPort, &iDCCAddr, 

} 

Matt Katzer 







&iDecoderClass, &iDecoderModel, &iError); 

TRACE( "TInterfaceDevice::DecoderGetModelFromCookie( 0x%08lx ) - Exiting: (%X)- Error\n", lCookie, iError ); 

return ( iDecoderModel ); 

Easily supported in multiple languages 

Page 34 

KAM 

TM

KAM * Where to from here 

• The API is on the CD-ROM 

Matt Katzer 







• Engine Commander® Software packaged 

has a show special with the developers kit 

included. 

• All KAMs CD-ROM have have PDF versions 

• The proposed API is in the NMRA approval 

process 

Page 35 

KAM 

TM

KAM * Questions 

Matt Katzer 

email: mkatzer@kamind.com 

web: http://www.kamind.com 

home: 503-291-1221 

Computer Dispatcher®, Engine Commander®, ecomifc®,Layout Commander®, Smart Decoder®, The Conductor®, 

Train Server®, kamind®, Train Tools® and Video Speed® are registered trademarks of KAM Industries. 

KAM Industries is a division of KAMIND associates, Inc. 

Other brands, products, trademarks or registered trademarks are properties of their respective holders. Matt Katzer 







Page 36 

KAM 

TM

KAM * Appendix 

• Railroad environment 

• Proposed NMRA API version 1.1 

(Train Server® version 2.121) 

Matt Katzer 







Page 37 

KAM 

TM

KAM * Railroad Environment 

• Must have NMRA DCC compatible engines 

– Pick a DCC supplier based on current requirement for your 

locomotive 

– By 2000, all locomotives in a price range above $100 will most likely 

have a decoder integrated into the unit 

• Command station equipment 

– Expect a hybrid; plan for multiple command stations on layout 

– Model expected; one for programming the other for command and 

control 

Control(com1) 

Command station interface 

MS-100, LI-100, 

hardware interface 

Lenz 

Programming or Control(com2) 

Command Station 

EasyDCC 

EasyDCC, Lenz, Digitrax 

Personal Computer 

Marlin, North Coast Engineering 

Wangrow, ZIMO 

Digitrax 

Multiple serial channel integration into DCC 

NCE 

Wangrow 

Matt Katzer 







Page 38 

KAM 

TM

KAM * NMRA Proposed API 

• Engine 

DccEngGetSpeed( ); 

DccEngSetSpeed( ); 

DccEngGetFunction( ); 

DccEngSetFunction( ); 

DccEngGetFunctionMax( ); 

DccEngGetName( ); 

DccEngSetName( ); 

DccEngGetFunctionName( ); 

DccEngSetFunctionName( ); 

DccEngGetSpeedSteps( ); 

DccEngSetSpeedSteps( ); 

• Consist 

DccEngConsistGetMax( ); 

DccEngConsistSetParent( ); 

DccEngConsistAddUnit( ); 

DccEngConsistRemoveUnit( ); 

DccEngConsistGetParent( ); 

Matt Katzer 







Page 39 

KAM 

TM

KAM * • Functions 

• DccCVGetValue(); 

DccCVSetValue(); 

DccCVGetStatus(); 

DccCVSetStatus(); 

DccCVGetName(); 

DccCVGetMaxRegister(); 

DccCVGetMinRegister(); 

• Accessory Commands 

DccAccGetFunction( ); 

DccAccSetFunction( ); 

DccAccGetFunctionAll( ); 

DccAccSetFunctionAll( ); 

DccAccGetFunctionMax( ); 

DccAccGetName( ); 

DccAccSetName( ); 

DccAccGetFunctionName( ); 

DccAccSetFunctionName( ); 

Matt Katzer 







NMRA Proposed API (cont.) 

Page 40 

KAM 

TM

KAM * • Command Station 

DccOprGetStationStatus(); 

DccOprTurnOnStation(); 

DccOprStartStation(); 

DccOprClearStation(); 

DccOprStopStation(); 

DccOprPowerOn(); 

DccOprPowerOff(); 

DccOprHardReset(); 

DccOprEmergencyStop(); 

• Programming 

DccProgramGetStatus(); 

DccProgramSetMode( ); 

DccProgramGetMode( ); 

DccProgramWriteCV( ); 

DccProgramReadCV( ); 

DccProgramWriteDecoderToDataBase( ); 

DccProgramReadDecoderFromDataBase( ); 

Matt Katzer 








Page 41 

KAM 

TM

KAM * • Communications 

DccProgramGetStatus(); 

DccProgramSetMode( ); 

DccProgramGetMode( ); 

DccProgramWriteCV( ); 

DccProgramReadCV( ); 

DccProgramWriteDecoderToDataBase( ); 

DccProgramReadDecoderFromDataBase( ); 

• Command 

DccCmdCommand( ); 

DccCmdConnect( ); 

DccCmdDisConnect( ); 

• Cab 

DccCabWriteMessage( ); 

DccCabReadMessage( ); 

DccCabSetDccObject( ); 

DccCabGetDccObject( ); 

DccCabAdd( ); 

DccCabDelete( ); 

DccCabTranslate( ); 

DccCabLookupDccObject( ); 

Matt Katzer 








Page 42 

KAM 

TM

KAM * • Decoder 

DccDecoderGetMaxModels(); 

DccDecoderGetModelName(); 

DccDecoderGetMaxAddress(); 

DccDecoderCheckAddrInUse(); 

DccDecoderGetMfgName( ); 

DccDecoderGetPowerMode( ); 

DccDecoderAddAddr() 

DccDecoderGetModelFacility() 

DccDecoderReconnectObject( ); 

DccDecoderChangeAddress( ) 

DccDecoderTranslate( ) 

DccDecoderSetModelToObject() 

DccDecoderGetMaxSpeed( ); 

DccDecoderGetObjectCount() 

DccDecoderGetObjectAtIndex() 

DccDecoderDel( ); 

DccDecoderGetErrorState( ) 

Matt Katzer 








Page 43 

KAM 

TM

KAM * • Time 

DccMiscGetClockTime( ); 

DccMiscSetClockTime( ); 

• Command Station 

DccMiscGetControllerName( ); 

DccMiscGetControllerNameAtPort( ); 

DccMiscGetCommandStationIndex( ); 

DccMiscMaxControllerID( ); 

DccMiscSetCommandStationValue( ); 

DccMiscGetCommandStationValue( ); 

DccMiscGetControllerFacility( ); 

• Misc 

DccMiscGetErrorMsg ( ); 

DccMiscGetApiName( ); 

DccMiscGetInterfaceVersion( ); 

DccMiscSaveData( ); 

Matt Katzer 








Page 44 

KAM 

TM

20000730_CLINIC_NMRA-00 Computer Interface App.pdf

Create successful ePaper yourself

Delete template?

Save as template?