Device::Message (M32, void *, M32, void *, M32, M32 *, M32 *, void *)

Message sends a message to the device. MODA system sends/receives messages sent by the user's program to the devices simulation engine nmpPhysics.

C++

M32 Message(M32 Message, void * pDataIn, M32 iDataInByteSize, void * pDataOut, M32 iDataOutByteSize, M32 * pReturnedByteSize, M32 * piDeviceResponse, void * pReserved);

Parameters

Parameters	Description
M32 Message	[in] Message to be sent to the device.
void * pDataIn	[in] Pointer on the data to be transmitted to the device, can be NULL.
M32 iDataInByteSize	[in] Size of data transmitted, in bytes. If the device judges that the transmitted data are too short, it answers MODA_EARGUMENT_OUTOFMEMORY. For example the SetVelocity motor command requires 1 float of 4 bytes...
void * pDataOut	[in/out] Device response buffer, can be NULL. Required if device have to respond value(s). For exemple distance sensor read.
M32 iDataOutByteSize	[out] Size of the receive buffer. The receive buffer must be of sufficient size : Read the message specific documentation to know data size. If the buffer is too small, the device answers MODA_ERESPONSE_OUTOFMEMORY.
M32 * pReturnedByteSize	[out] Size really used by the answer, can be NULL. Gives the size, in bytes, which is really used by the answer. The size is lower or equal to the size of the receive buffer. The interpretation these bytes depends of message sent to the device.
M32 * piDeviceResponse	[out] Pointer on the device error message, can be NULL If piDeviceResponse is not NULL, Message fills the M32 pointed by piDeviceResponse with the code returned by the device.
void * pReserved	[in/out] Reserved for groups management messages (see DevicesGroup). If the message does not relate to a group, pReserved must be NULL.

Returns

MODA_EOK if the system sent message to the device, an error value otherwise (see MODA Errors)

Description

How does it works :

MODA optimizes the network calls by removing the device response frame from the server when not required: for example changing a servo-motor does not require a server response. The device response is automatically get when :

An answer is necessary (pDataOut not NULL): for example reading of a measurement of distance, and/or
The device return code is wished by the user (piDeviceResponse not NULL).

The Message function provides 2 error messages: The system error code (returned by the Message call) and the device error(placed in piDeviceResponse if non NULL).

The fact ignore the device error code accelerates the networks exchanges considerably since only one frame is transmitted between the user's program and the server. When piDeviceResponse is not NULL, 2 frames are required.

MODA server message management:

State of the device	Action MODA
On	The message is sent to the device. The error code returned in piDeviceResponse is the device response, system response is MODA_EOK.
Off	The Message is not sent to the device. The error code returned in piDeviceResponse is MODA_EDEVICEISOFF, system response is MODA_EOK.
AutoOn	If the device is Off, it is started by MODA then the message is sent. If the device is On, the message is sent directly.

Remarks

MODA provides the Devicexxxxx classes for the engine's internal devices (Devices). These classes, for example DeviceMotor, export functions which avoid user to use the message management system : for example the source code of DeviceMotor::SetVelocityRPS (DeviceMotor.cpp in ModaSTD)

bool DeviceMotor::SetVelocityRPS( float RdPerSec,M32 *pDeviceResponse,void *pReserved)
    {
    M32 ret=Message(Moda::STDCoreDevicesMessages::COREDEVICEMOTOR_SETVELOCITY,&RdPerSec,sizeof(RdPerSec),NULL,NULL,0,pDeviceResponse,pReserved);
    return(ret==Moda::Commons::MODA_EOK);
    }