IO APIs
IO API Services
IO (input output) APIs provide the ability for an LMU-5530 application to access inputs, outputs, input bias, analog-to-digital converters (ADCs), wake-up sources, and other set operations running on STM8 processors.
calamp_stm_cli demonstrates different IO operations supported by IO APIs and helps print the whole list of commands.
Introduction
This page defines CalAmp's LMU-55XX sleep mode, IO management application (STM-Manager) services, and interfaces for Linux applications to access the platform's inputs, input bias, outputs, ADCs, 1BitBus devices, wake-up sources, and several set operations in the coprocessor (STM8).
The STM-Manager is a Linux process application started by the Linux init daemon. The STM-Manager is responsible for monitoring the coprocessor (STM8) by generating several get serial uart commands. The STM-Manager is also responsible for accepting messages from multiple Linux applications to set output(s), set input bias, enable sleep mode, and so on.
The STM-Manager provides several Linux interprocess communication (IPC) resources:
- Shared memory: For Linux applications to access IO device states.
- Message queues: For Linux applications to send request messages to the STM8 coprocessor.
The STM-Manager Shared Memory Interface
struct stm_shm {
uint32_t state; /* see STM_STATE defs */
uint32_t stm8_interval; /* monitor STM8 io in millisecs */
uint32_t que_interval; /* monitor input queue in secs */
uint32_t max_sleep_clients; /* default max clients for sleep notify */
uint32_t ttl_sleep_clients; /* total attached sleep notify clients */
uint32_t sleep_clients[STM_MAX_SLEEP_CLIENTS];
char stm_mgr_version[3]; /* STM-Manager version */
char stm8_ver[3]; /* STM8 version response */
uint32_t wakeup_status; /* wakeup status data */
char default_wakeup_str[32]; /* wakeup status string */
uint32_t wakeup_source; /* wakeup source */
uint32_t default_wakeup_mask; /* default wakeup mask */
uint32_t prev_wakeup_mask; /* previous wakeup mask */
uint32_t curr_wakeup_mask; /* current wakeup mask */
/* sleep parameters */
uint32_t stm8_sleep_motion_low; /* STM8 motion low threshold */
uint32_t stm8_sleep_motion_high; /* STM8 motion high threshold */
uint32_t stm8_sleep_motion_max; /* STM8 motion max threshold */
uint32_t stm8_sleep_motion_cnt; /* STM8 motion cnt (0-80 ) */
uint32_t stm8_sleep_motion_window; /* STM8 motion window (1-30 ) */
uint32_t stm8_sleep_input_state; /* sleep input state */
uint32_t stm8_sleep_timedate; /* sleep epoch UTC timedate */
uint32_t stm8_sleep_wakeup_mask; /* sleep wakeup mask */
/* IO */
uint32_t prev_input_state; /* inputs 0-7 , bit0 = input_0...*/
uint32_t curr_input_state; /* inputs 0-7 , bit0 = input_0...*/
uint32_t prev_output_state; /* outputs 0-6 , bit0 = outputs_0...*/
uint32_t curr_output_state; /* outputs 0-6 , bit0 = outputs_0...*/
uint32_t prev_input_bias; /* input_bias settings for inputs 0-7 */
uint32_t curr_input_bias; /* input_bias settings for inputs 0-7 */
uint32_t prev_timedate; /* previous set timedate */
uint32_t curr_timedate; /* current set timedate */
uint32_t prev_adc[8]; /* RAW adc values */
uint32_t curr_adc[8]; /* RAW adc values */
/* 1BitBus data */
int32_t bbus1_state; /* 1BitBus sensor state */
uint8_t bbus1_romcode; /* 1BitBus rom code */
int32_t bbus1_device_ct; /* 1BitBus total sensors on bus1 */
uint8_t bbus1_devnum[8][9]; /* 1BitBus sensor address */
uint8_t bbus1_data[9]; /* 1Bitbus sensor, pin8 on adaptor */
double bbus1_celsius; /* temperature in celsius 0.1 */
int32_t bbus1_temperature; /* temperature */
int32_t bbus2_state; /* 1BitBus sensor state */
uint8_t bbus2_romcode; /* 1BitBus rom code */
int32_t bbus2_device_ct; /* 1BitBus total sensors on bus2 */
uint8_t bbus2_devnum[8][9]; /* 1BitBus sensor addr */
uint8_t bbus2_data[9]; /* 1Bitbus bus 1 data, pin10 on adaptor */
#ifdef LMU5530_PEG
unsigned long last_counter_time[2];
uint32_t debug_mask;
u_int16_t tsc; /*gets increment from lmu side anytime it sets the system time */
unsigned long ctime; /* current time */
unsigned long ntime; /* new time */
#endif
};
See Appendix A for various definitions of shared memory (such as state and the wake-up mask).
Accessing STM-Manager's Shared Memory Region
To access STM-Manager's shared memory region, an application needs to access the LMU file system to retrieve the ftok path needed to create a shared memory ID. The following C code is an example:
#include <sys/types.h>
#include <stddef.h>
#include <string.h>
#include <unistd.h>
#include <stdbool.h>
#include <errno.h>
#include <stdlib.h>
#include <syslog.h>
#include <getopt.h>
#include <sys/ipc.h>
#include <sys/shm.h>
#include <sys/msg.h>
#include <sys/stat.h>
#include <calamp/stm_shm_defs.h>
#include <calamp/stm_msg_defs.h>
#include "stm_mgr.h" /* need to define u8 typedef for stm_comm.h */
#include "stm_shm.h" /* need shared memory defs */
#include "stm_msg.h" /* need stm manager msg services */
void display_stm_shm_info( void )
{
int i=0;
int id;
key_t key;
struct stm_shm *info;
key = ftok ( /etc/calamp/stm/shm, 's' );
if (key == -1) {
perror ("ftok");
exit (EXIT_FAILURE);
}
id = shmget (key, 0, 0);
if (id == -1) {
perror ("shmget");
exit (EXIT_FAILURE);
}
info = shmat (id, NULL, SHM_RDONLY);
if (info == (void *) -1) {
perror ("shmat");
exit (EXIT_FAILURE);
}
printf("\n");
printf("stm_mgr_version 2.2.0 \n");
printf("stm8_interval %dms\n", info->stm8_interval);
printf("que_interval %ds\n", info->que_interval);
printf("max_sleep_clients %d\n", info->max_sleep_clients);
printf("\n");
printf("******************** stm8 info **************************\n");
printf("stm8_ver %d.%d.%d\n",
info->stm8_ver[0],
info->stm8_ver[1],
info->stm8_ver[2]);
printf("\n");
printf("wakeup_status 0x%x\n", info->wakeup_status);
printf("wakeup_status_str %s\n", info->wakeup_source_str);
printf("wakeup_source 0x%x\n", (uint32_t)info->wakeup_source);
printf("default_wakeup_mask 0x%x\n", (uint32_t)info->default_wakeup_mask);
printf("curr_wakeup_mask 0x%x\n", (uint32_t)info->curr_wakeup_mask);
printf("curr_input_state 0x%x\n", (uint32_t)info->curr_input_state);
printf("curr_input_bias 0x%x\n", (uint32_t)info->curr_input_bias);
printf("curr_output_state 0x%x\n", (uint32_t)info->curr_output_state);
printf("curr_set_timedate %u\n", info->curr_timedate);
printf("\n");
for (i = 0; i < 8; i++)
{
printf("curr_adc_%d %d\n", i, info->curr_adc[i]);
}
printf("------------------ 1bitbus BUS1----------------------\n");
printf("\n");
printf("romcode 0x%x \n", info->bbus1_romcode);
printf("device_ct %u \n", info->bbus1_device_ct);
printf("\n");
printf("bus_data(bytes8-0):0x%x 0x%x 0x%x 0x%x 0x%x 0x%x 0x%x 0x%x 0x%x\n",
info->bbus1_data[8], info->bbus1_data[7],
info->bbus1_data[6], info->bbus1_data[5],
info->bbus1_data[4], info->bbus1_data[3],
info->bbus1_data[2], info->bbus1_data[1],
info->bbus1_data[0]);
printf("\n");
printf("------------------ 1bitbus BUS2----------------------\n");
printf("\n");
printf("romcode 0x%x \n", info->bbus2_romcode);
printf("device_ct %u \n", info->bbus2_device_ct);
printf("\n");
printf("bus_data(bytes8-0):0x%x 0x%x 0x%x 0x%x 0x%x 0x%x 0x%x 0x%x 0x%x\n",
info->bbus2_data[8], info->bbus2_data[7],
info->bbus2_data[6], info->bbus2_data[5],
info->bbus2_data[4], info->bbus2_data[3],
info->bbus2_data[2], info->bbus2_data[1],
info->bbus2_data[0]);
printf("\n");
/* detach from shared memory region */
shmdt (info);
return;
}
STM-Manager's Queue Interface
The STM-Manager accepts Linux message queue requests from multiple applications. There is an input and output queue that any application can access for requests/responses. Most of the STM-Manager requests do not provide a response via its output queue; rather, it is up to the requesting application to read shared memory to see if any state change occurred due to the request.
Accessing STM-Manager's Inbound Queue
To access the STM-Manager's input queue, the requesting application needs to allocate its queue ID from Linux, as shown in the following example:
#include <sys/types.h>
#include <stddef.h>
#include <string.h>
#include <unistd.h>
#include <stdbool.h>
#include <errno.h>
#include <stdlib.h>
#include <syslog.h>
#include <getopt.h>
#include <sys/ipc.h>
#include <sys/shm.h>
#include <sys/msg.h>
#include <sys/stat.h>
#include <calamp/stm_shm_defs.h>
#include <calamp/stm_msg_defs.h>
static int send_message (struct stm_mgr_msg *msg)
{
int id;
key_t key;
key = ftok ( “/etc/calamp/stm/msg”, 's');
if (key == -1){
perror ("ftok");
return -1;
}
id = msgget (key, S_IWUSR);
if (id == -1){
perror ("mssget");
return -2;
}
if (msgsnd (id, msg, sizeof(struct stm_mgr_msg), 0) == -1) {
perror ("msgsnd");
return -3;
return 0;
}
Accessing STM-Manager's Outbound Queue
To access the STM-Manager's output queue, the requesting application needs to allocate its queue ID from Linux; here is an example:
#include <sys/types.h>
#include <stddef.h>
#include <string.h>
#include <unistd.h>
#include <stdbool.h>
#include <errno.h>
#include <stdlib.h>
#include <syslog.h>
#include <getopt.h>
#include <sys/ipc.h>
#include <sys/shm.h>
#include <sys/msg.h>
#include <sys/stat.h>
#include <calamp/stm_shm_defs.h>
#include <calamp/stm_msg_defs.h>
static int recv_message (struct stm_mgr_msg *msg, int32_t mtype_dst )
{
int id, rc;
key_t key;
int32_t rsp_len = 0;
if ( msg == NULL )
{
printf(" msg is NULL!! \n");
return -1;
}
key = ftok (STM_MSG_FTOK_FILE, STM_MSG_RECV_FTOKID);
if (key == -1){
perror ("ftok");
return -1;
}
id = msgget (key, S_IWUSR);
if (id == -1){
perror ("mssget");
return -2;
}
printf( " waiting for response from stm-manager ..\n");
memset ( msg, 0, sizeof(struct stm_mgr_msg ));
rsp_len = ( sizeof( struct stm_mgr_msg) - sizeof(uint32_t) );
/* Waits for the response */
rc = msgrcv (id, msg, rsp_len, mtype_dst, MSG_NOERROR );
if ( rc == -1 )
{
printf(" msgrcv with error %s \n", strerror(errno));
}
return rc;
}
Sending a Command to STM-Manager's Outbound Queue
For sending commands, both input and output queues are used. To send a command, you use STM-Manager’s input queue, and to receive the response, you use the output queue. Requester applications can use any commands defined in sections 1-9 to STM8 by following the example below. In this example, the user wants to retrieve the watchdog content:
int main (int argc, char *argv[])
{
int id;
key_t key;
int32_t ch = 0, rc = 0;
int32_t i = 0, index = 0;
int32_t opcode = 0;
uint32_t option_1 = 0;
uint32_t option_2 = 0;
uint32_t option_3 = 0;
uint32_t option_4 = 0;
uint32_t seq=0;
struct stm_mgr_get_wdog_rsp wrsp;
struct stm_mgr_msg msg;
struct stm_mgr_msg rsp;
opcode = STM_MGR_OPCODE_SET_WDOG;
memset ( &msg, 0, sizeof( msg ) );
/* fill in message header */
msg.mtype = MTYPE_STM_DST;
msg.mtype_src = MTYPE_APP_SRC; /* see explanation below */
msg.seq = seq++;
msg.opcode = opcode;
rc = send_message ( &msg ); /* explained in section 1.6 */
/* wait for response */
memset ( &wrsp, 0, sizeof(wrsp ));
rc = recv_message ( &wrsp, MTYPE_APP_DST ); /* explained in section 1.7 */
}
You can select the msg.mtype_src from the following numbers:
| Message Type | Message Value |
|---|---|
| MTYPE_APP_SRC | 129 |
| MTYPE_APP_2_SRC | 131 |
| MTYPE_APP_3_SRC | 133 |
Up to three coresident apps can run at the same time.
STM-Manager's Request Message Operations
You can issue the following commands to STM8:
stm-manager-msg-opcodes
| Opcode | Value | Description |
|---|---|---|
| NOTIFY_SLEEP | 1 | Request to get notified by STM before SLEEP is processed. |
| GOTO_SLEEP | 2 | Perform SLEEP. |
| SET_OUTPUTS | 3 | Set the output(s) operation. |
| SET_INPUT_BIAS | 4 | Set the input_bias(s) operation. |
| SET_RTC | 5 | Set the rtc operation. |
| GET_RTC | 6 | Get the timedate (epoch UTC) from STM8 RTC. |
| SET_STM8_INTVL | 7 | Set the STM-Manager monitor interval. |
| SET_QUE_INTVL | 8 | Set the STM-Manager queue interval. |
| 1BB_ID_DETECT | 9 | Read the 1BitBus sensor’s address on pin8 of the 22 IO adaptor. |
| 1BB_TS_DISCOVER | 10 | Discover the 1BitBus temperature sensors' addresses on pin10 of the 22 IO adaptor. |
| 1BB_TS_DETECT | 11 | Read the 1BitBus temperature sensors' addresses on pin10 of the 22 IO adaptor. |
| 1BB_TS_READ_TEMP | 12 | Read the 1BitBus temperature sensor’s temperature in degrees Celsius. |
| STM_PEEK | 13 | Read a memory address from STM8. |
| STM_POKE | 14 | Write a byte to a memory address in STM8. |
| STM_OUT_BLINK | 15 | Set an output to a blink with a configurable frequency. |
| STM_SET_WDOG | 16 | Set the STM8 watchdog. |
| STM_GET_WDOG | 17 | Get the STM8 watchdog. |
| Reserved | 18 | Reserved. |
| Reserved | 19 | Reserved. |
| Reserved | 20 | Reserved. |
| STM_GET_COUNTER | 21 | Get the counter value. |
| STM_GET_TIMESTAMP | 22 | Get the timestamp value. |
| STM_GET_HISTORY | 23 | Get the history of the assigned channel during bootup. |
| Reserved | 24 | Reserved. |
| STM_SET_DEBUG_MODE | 25 | Enable/disable debug mode in the STM-Manager. |
| STM_WKP_FILTER | 26 | Enable the STM uart filter for wake-up. |
| STM_GET_INPUT | 27 | Get inputs if there is a change. |
NOTIFY_SLEEP Description
The requester can request that STM-Manager notify the application whenever SLEEP processing has been requested by another application. The STM-Manager will notify the application with a Linux signal (SIGUSR1). There is no response message generated by the STM-Manager when this request is processed.
NOTIFY_SLEEP_REQUEST Message
struct stm_mgr_notify_sleep_req
{
int32_t mtype; /* stm-mgr-dst mtype */
int32_t mtype_src; /* caller's src mtype */
int32_t seq; /* caller's sequence number */
int32_t opcode; /* opcode =1 */
int32_t pid; /* process id of application for sending SIGUSR1 */
};
where : mtype = 160 ( MTYPE_STM_DST )
mtype_src = (MTYPE_APP_SRC, MTYPE_APP_2_SRC, MTYPE_APP_3_SRC or MTYPE_STM_CLI_SRC)
seq = caller's sequence number
opcode = 1
SET_OUTPUTS Message Description
The requester can set a single output to either on or off, or a group of outputs to various modes. The output signals are defined as active_low signals, so by default, all outputs are set to off by setting each output to one (1). To enable an output signal, set the output value to zero (0). The factory default value of the LMU-5530 output signal is 0xC07F.
The requester must first read the STM-Manager’s shared memory region’s curr_output_state, then either set or clear any output bits, and then send the SET_OUTPUTS message to the STM-Manager.
The following are the LMU-5530 output signal definitions:
| Output | Bit # |
|---|---|
| Output_0 | 0 |
| Output_1 | 1 |
| Output_2 | 2 |
| Output_3 | 3 |
| Output_4 | 4 |
| Output_5 | 5 |
| Output_6 | 6 |
| SIM_SELECT | 7 |
| CELL_PWR | 8 |
| Reserved | 9-13 |
| 1BB_2_BOOST | 14 |
| 1BB_1_BOOST | 15 |
| Reserved | 16-31 |
When the STM-Manager receives the SET_OUTPUTS message from a Linux application, it will parse the requesting message and send the command to the coprocessor to SET the selected output signals.
SET_OUTPUTS Request Structure
struct stm_mgr_set_outputs_req
{
int32_t mtype; /* stm-mgr-dst mtype */
int32_t mtype_src; /* caller's src mtype */
int32_t seq; /* caller's sequence number */
int32_t opcode; /* opcode =3 */
uint32_t output_mask; /* which outputs to set */
uint32_t output_value_mask; /* what values to set */
};
where : mtype = 160 (MTYPE_STM_DST )
mtype_src = ( MTYPE_APP_SRC, MTYPE_APP_2_SRC, MTYPE_APP_3_SRC or MTYPE_STM_CLI_SRC)
seq = caller’s sequence number
opcode = 3
output_mask = bit mask 0-31 ,
output_value = bit mask 0-31
For example, to set output_0, with the initial output signal setting 0xC07F, the output_value will be 0xC07E; to clear output_0, with the initial output signal setting 0xC07E, the output_value will be 0xC07F.
SET_INPUT_BIAS Message Description
The requester can set a single input_bias signal to either on or off, or a group of input_bias signals to various modes. The input_bias signals are defined as active_low or active_high signals, so by default, all input_bias signals are set to active_high except for input_bias_0 (ignition), which is set to active_low.
The LMU-55XX supports seven input-bias signals. Input-bias setting 0 is reserved for the ignition signal, which is always set to active_low.
When the STM-Manager receives the SET_INPUT_BIAS message from a Linux application, it will parse the requesting message and send a command to the STM8 to set each input_bias signal to its corresponding value.
SET_INPUT_BIAS Request Structure
struct stm_mgr_set_input_bias_req
{
int32_t mtype; /* stm-mgr-dst mtype */
int32_t mtype_src; /* caller's src mtype */
int32_t seq; /* caller's sequence number */
int32_t opcode; /* opcode =4 */
uint32_t input_bias_mask; /* which input_bias signal(s) to set */
uint32_t input_bias_val_mask; /* what values to set */
};
where : mtype = 160 (MTYPE_STM_DST)
mtype_src = (MTYPE_APP_SRC, MTYPE_APP_2_SRC, MTYPE_APP_3_SRC or MTYPE_STM_CLI_SRC)
seq = optional
opcode = 4
input_bias_mask = bit mask 0-31 ,
input_bias_val_mask = bit mask 0-31
SET_RTC Message Description
The requester can set the STM8 RTC (real-time clock) calendar date and time; it is the requester's responsibility to ensure that the date and time are sometime in the future because the STM-Manager does not check for date/time values. The date/time is in epoch time (since Jan 01, 1990) for GMT.
When the STM-Manager receives the SET_RTC message from a Linux application, it will parse the requesting message and send the command to the STM8 for updating the real-time clock device.
SET_RTC Request Message Structure
struct stm_mgr_set_rtc_req
{
int32_t mtype; /* stm-mgr-dst mtype */
int32_t mtype_src; /* caller's src mtype */
int32_t seq; /* caller's sequence number */
int32_t opcode; /* opcode =5 */
uint32_t timedate; /* epoch timedate for rtc */
};
where: mtype = 160 ( MTYPE_STM_DST)
mtype_src = ( MTYPE_APP_SRC, MTYPE_APP_2_SRC, MTYPE_APP_3_SRC or MTYPE_STM_CLI_SRC )
seq = optional
opcode = 5
GET_RTC Message Description
The requester can get the STM8 RTC calendar date and time; the application sends the GET_RTC message, and the response will be queued to the STM-Manager’s outbound queue with the caller’s destination MTYPE and OPCODE. The date/time is in UTC epoch time.
When the STM-Manager receives the GET_RTC message from a Linux application, it will parse the requesting message and send the command to the STM8 for retrieving the real-time clock device calendar date and time. The STM-Manager will then queue the GET_RTC response to the STM-Manager’s outbound queue with the caller’s DST MTYPE. (The caller’s DST MTYPE is one less than its SRC_MTYPE.)
GET_RTC Request Message Structure
struct stm_mgr_get_rtc_req
{
int32_t mtype; /* stm-mgr-dst mtype */
int32_t mtype_src; /* caller's src mtype */
int32_t seq; /* caller's sequence number */
int32_t opcode; /* opcode = 6 ( GET_RTC ) */
uint32_type_rsp; /* app type that originates the request */
};
where : mtype = 160 ( MTYPE_STM_DST)
mtype_src = (MTYPE_APP_SRC, MTYPE_APP_2_SRC, MTYPE_APP_3_SRC or MTYPE_STM_CLI_SRC)
type_rsp = (MTYPE_APP_DST, MTYPE_APP_2_DST, MTYPE_APP_3_DST, MTYPE_STM_CLI_DST)
seq = optional
opcode = 6
GET_RTC Response Message Structure
struct stm_mgr_get_rtc_rsp
{
int32_t mtype; /* caller’s dst mtype */
int32_t mtype_src; /* stm-manager src ( 161) */
int32_t seq; /* caller's sequence number */
int32_t opcode; /* GET_RTC (6) */
uint32_t timedate; /* timedate in UTC epoch time */
};
GOTO_SLEEP Message Description
The requester can request that the LMU-55XX IMX6 processor go to sleep. After this message is properly parsed by the STM-Manager, it signals all the registered applications that sleep is being performed. Then the STM-Manager sends the sleep message to the STM8 coprocessor. When the STM8 parses the sleep command message, the LMU-55XX CPU is halted, and the coprocessor goes into low power mode.
When the GOTO_SLEEP message is sent from the Linux application, it won't expect a response in return.
STM-Manager GOTO_SLEEP Request Message Structure
struct stm_mgr_goto_sleep_req
{
int32_t mtype; /* stm-mgr-dst mtype ( 160 ) */
int32_t mtype_src; /* caller's src mtype */
int32_t seq; /* caller's sequence number */
int32_t opcode; /* opcode = 2 */
int32_t low; /* motion_low_threshold */
int32_t high; /* motion_high_threshold */
int32_t max; /* motion_max_threshold */
int32_t window; /* motion sample rate window */
int32_t cnt; /* motion counter */
uint32_t wakeup_mask; /* wakeup mask setting */
uint32_t input_state; /* current input signal values */
uint32_t timedate; /* epoch timedate in seconds to wakeup RTC wakeup selected */
};
SET_STM8_INTVL Message Description
The requester can request that the STM-Manager monitor the platform's IO signal's frequency interval. The default interval is 100 milliseconds. If the requester needs to change the frequency, it must be an interval longer than 100 milliseconds and shorter than 10,000 milliseconds.
The STM-Manager retrieves the following messages from STM8 and updates the shared memory within this interval:
STM_GET_INPUT
STM_GET_BIAS
STM_GET_OUTPUTS
STM_GET_ADC
When the STM-Manager receives the SET_STM8_INTVL message from a Linux application, it will parse the requesting message. No response is returned to the Linux application.
SET_STM8_INTVL Message Structure
struct stm_mgr_set_stm8_intvl_req
{
int32_t mtype; /* stm-mgr-dst mtype (160) */
int32_t mtype_src; /* caller's src mtype */
int32_t seq; /* caller's sequence number */
int32_t opcode; /* opcode = 7 */
uint32_t stm8_interval; /* stm8_interval in milliseconds */
};
SET_QUE_INTVL Message Description
The requester can request that the STM-Manager monitor its application queue frequency interval. The default interval is 5 seconds. If the requester needs to change the frequency, it must be an interval longer than 1 second.
When the STM-Manager receives the SET_QUE_INTVL message from a Linux application, it will parse the requesting message. No response is returned to the Linux application.
SET_QUE_INTVL Message Structure
struct stm_mgr_set_que_intvl_req
{
int32_t mtype; /* stm-mgr-dst mtype ( 160) */
int32_t mtype_src; /* caller's src mtype */
int32_t seq; /* caller's sequence number */
int32_t opcode; /* opcode = 8 */
uint32_t interval; /* interval in seconds */
};
1BB_ID_DETECT Message Description
The requester can request that the STM-Manager detect a 1BitBus sensor on BUS1 (pin8) on the 22pin IO adaptor port. It is the operator/installer’s responsibility to attach the 1BitBus sensor correctly on the 22pin IO adaptor port.
When the STM-Manager receives the request message, it will send a message to the STM8 to perform the detection. Following this, the bbus1_data in the STM-Manager shared memory region will be updated with the 1BitBus 64 bit address, and the bbus1_device_ct will be incremented if the sensor is either an iButton reader or a DS18S20/DS18B20 temperature sensor.
1BB_ID_DETECT Request Message Structure
struct stm_mgr_1bb_detect_req
{
int32_t mtype; /* stm-mgr-dst mtype ( 160) */
int32_t mtype_src; /* caller's src mtype */
int32_t seq; /* caller's sequence number */
int32_t opcode; /* opcode = 9 */
uint32_t busid; /* busid = 0 or 1 */
int32_t mtype_rsp; /* dst mtype for response}; */
1BB_TS_DISCOVER Message Description
The requester can request that the STM-Manager detect a 1BitBus sensor on BUS1 (pin10) on the 22pin IO adaptor port. It is the operator/installer’s responsibility to attach the 1BitBus temperature sensors correctly on the 22pin IO adaptor port.
When the STM-Manager receives the request message, it will send a message to the STM8 to perform the discovery; the STM-Manager’s shared memory region’s bbus2_data will be updated with the 1BitBus 64bit address; and the bbus2_device_ct will be incremented if DS18S20/DS18B20/DS28EA00 temperature sensors are discovered.
If a DS28EA00 multidrop temperature sensor is attached to pin10 of the BUS2 1BitBus, there can be up to eight temperature sensors. It can take up to 10 seconds to complete the discovery. The STM-Manager will update the bbus2_devnum, bbus2_romcode, and bbus2_data with the discovered temperature sensors. This discovery mechanism can take up to 10 seconds to complete.
1BB_TS_DISCOVER Request Message Structure
struct stm_mgr_1bb_detect_req
{
int32_t mtype; /* stm-mgr-dst mtype ( 160) */
int32_t mtype_src; /* caller's src mtype */
int32_t seq; /* caller's sequence number */
int32_t opcode; /* opcode = 10 */
uint32_t busid; /* busid = 0 or 1 */
int32_t mtype_rsp; /* dst mtype for response */
};
1BB_TS_DETECT Message Description
The requester can request that the STM-Manager detect a 1BitBus sensor on BUS1 (pin10) on the 22pin IO adaptor port. It is the operator/installer’s responsibility to attach the 1BitBus temperature sensor correctly on the 22pin IO adaptor port. Only DS18S20, DS18B20, DS1822, DS1825, and DS28EA00 sensors are supported.
When the STM-Manager receives the request message, it will send a message to the STM8 to perform the detection on 1BitBus BUS2. The temperature sensor’s 1BitBus address will be updated in the STM-Manager’s shared memory bbus2_data [9] array.
1BB_TS_DETECT Request Message Structure
struct stm_mgr_1bb_detect_req
{
int32_t mtype; /* stm-mgr-dst mtype ( 160) */
int32_t mtype_src; /* caller's src mtype */
int32_t seq; /* caller's sequence number */
int32_t opcode; /* opcode = 11 */
uint32_t busid; /* busid = 1 */
int32_t mtype_rsp; /* dst mtype for response */
};
1BB_TS_READ_TEMP Message Description
The requester can request that the STM-Manager read the temperature (in degrees Celsius) from a 1BitBus sensor on BUS1 (pin10) on the 22pin IO adaptor port. It is the operator/installer’s responsibility to attach the 1BitBus temperature sensor correctly on the 22pin IO adaptor port. Only DS18S20, DS18B20, DS1822, DS1825, and DS28EA00 sensors are supported.
It is the caller’s responsibility to perform a TS_DISCOVER/TS_DETECT before performing the
TS_READ_TEMP because if the temperature sensor attached to the LMU is a multidrop temperature sensor, the TS_DISCOVER will update the shared memory bbus2_devnum arrays properly. Otherwise, if the temperature sensor attached to the LMU is a standalone sensor, the bbus2_romcode will be updated with the correct 1BitBus address, and bbus2_devnum [0] will contain the same 1BitBus data.
When the STM-Manager receives the request message, it will send a message to the STM8 to perform the read temperature conversion on 1BitBus. The temperature sensor’s 1BitBus temperature will be updated in the STM-Manager’s shared memory bbus2_celsius variable.
1BB_TS_READ_TEMP Request Message Structure
struct stm_mgr_1bb_ts_read_temp_req
{
int32_t mtype; /* stm-mgr-dst mtype ( 160) */
int32_t mtype_src; /* caller's src mtype */
int32_t seq; /* caller's sequence number */
int32_t opcode; /* opcode = 12 */
uint32_t busid; /* busid = 1 */
uint32_t multi_drop; /* multi_drop = 0 or 1 */
uint32_t index; /* devnum index */
uint8_t devnum[9]; /* sensor's address */
};
STM_PEEK for a Memory Address
The requester can request that the STM-Manager read a memory address and return it as an unsigned 8 bit character.
STM_PEEK Request Message Structure
struct stm_mgr_peek_req
{
int32_t mtype; /* stm-mgr-dst (160) */
int32_t mtype_src; /* caller's src mtype */
int32_t seq; /* caller's sequence number */
int32_t opcode; /* opcode = 13 */
uint32_t peek_addr; /* which address to read */
uint32_type_rsp; /* app type that orogonates the request */
};
STM_PEEK Response Message Structure
struct stm_mgr_peek_rsp
{
int32_t mtype; /* caller's dst mtype */
int32_t mtype_src; /* stm-mgr-src (161) */
int32_t seq; /* caller's sequence number */
int32_t opcode; /* opcode = 13 */
uint32_t data; /* memory content */
};
STM_POKE for a Memory Address
The requester can request that the STM-Manager write a value to a memory address.
STM_POKE Request Message Structure
struct stm_mgr_poke_req
{
int32_t mtype; /* stm-mgr-dst (160) */
int32_t mtype_src; /* caller's src mtype */
int32_t seq; /* caller's sequence number */
int32_t opcode; /* opcode = 14 */
uint32_t poke_addr; /* which address to write to */
uint32_t poke_val; /* address content */
};
Set an Output to Blink Using STM_OUT_BLINK
The requester can request that the STM-Manager start blinking an output at a predefined rate.
STM_OUT_BLINK Request Message Structure
struct stm_mgr_notify_blink_req
{
int32_t mtype; /* stm-mgr-dst (160) */
int32_t mtype_src; /* caller's src mtype */
int32_t seq; /* caller's sequence number */
int32_t opcode; /* opcode = 15 */
uint8_t stm_output; /* output number - bitmask */
uint8_t stm_pattern; /* Blinking pattern */
uint8_t stm_count; /* Number of pulses */
};
In the preceding, you'll see the following:
- stm_output: A bitmask of the output you want to toggle.
- stm_pattern: A blinking pattern. The resolution of each bit is 125 ms.
So if you select 0x0F(00001111), that means 2 HZ (4*125= off,4*125= on).
If you select 0xAA(10101010), that means 4 HZ (1*125= off,1*125= on). - stm_count:
<0>: Blinking is in continuous mode. You can disable this mode by writing to that specific output, either turning it off or on.
<a number>: The number of blinks. You can decide how many times to toggle the output based on the defined pattern.
Set the Value of the STM8 Watchdog Timer Using STM_SET_WDOG
The requester can request that the STM-Manager set its watchdog timer value.
STM_SET_WDOG Request Message Structure
struct stm_mgr_set_wdog_req
{
int32_t mtype; /* stm-mgr-dst (160) */
int32_t mtype_src; /* caller's src mtype */
int32_t seq; /* caller's sequence number */
int32_t opcode; /* opcode = 16 */
uint32_t time_out; /* time in second */
};
When using STM_SET_WDOG, be aware of the following:
- The watchdog timer by default is 300 seconds.
- To disable the watchdog, set the time to zero.
- Don’t set the watchdog timer to fewer than 50 seconds.
Get the Value of the STM8 Watchdog Timer Using STM_GET_WDOG
The requester can request that the STM-Manager return its watchdog timer value.
STM_GET_WDOG Request Message Structure
struct stm_mgr_get_wdog_req
{
int32_t mtype; /* stm-mgr-dst (160) */
int32_t mtype_src; /* caller's src mtype */
int32_t seq; /* caller's sequence number */
int32_t opcode; /* opcode = 17 */
uint32_type_rsp; /* app type that orogonates the request */
};
STM_GET_WDOG Response Message Structure
struct stm_mgr_get_wdog_rsp
{
int32_t mtype; /* caller's dst mtype */
int32_t mtype_src; /* stm-mgr-src (161) */
int32_t seq; /* caller's sequence number */
int32_t opcode; /* opcode = 17 */
uint32_t data; /* watchdog value in second */
};
STM_GET_TIMESTAMP Description
The requester can request that the STM-Manager start sending the timestamp for a specific channel.
STM_GET_TIMESTAMP Request Message Structure
struct stm_mgr_timestamp_req
{
int32_t mtype; /* stm-mgr-dst (160) */
int32_t mtype_src; /* caller's src mtype */
int32_t seq; /* caller's sequence number */
int32_t opcode; /* opcode = 22 */
uint32_t type_rsp; /* msg type that originates the request */
uint8_t mode; /* one shot or periodic mode */
int32_t time; /* time interval in ms */
uint8_t channel; /* select channel(s) to read */
};
In the preceding, you'll see the following:
-
mode:
0: One shot
1: Periodic based on interval time
2: Disables the periodic mode -
time: The time in milliseconds between each response from STM-Manager if there is data available
-
channel: You can select which timestamp channel to be read with this command. It is a bitmask as defined below:
0x01: Channel 1
0x02: Channel 2
0x04: Channel 3
0x08: Channel 4
0x0F: To enable all channelsSTM_GET_TIMESTAMP Response Message Structure
struct stm_mgr_timestamp_rsp
{
int32_t mtype; /* caller's dst mtype */
int32_t mtype_src; /* stm-mgr-src (161) */
int32_t seq; /* caller's sequence number */
int32_t opcode; /* opcode = 22 */
uint8_t channel; /* channel number */
uint8_t count; /* number of samples per packet */
uint8_t more; /* more data to come for this request */
unit8_t data[count][5]; /* time stamp data */
};
When using STM_GET_TIMESTAMP, be aware of the following:
- The length of the received packet is variable, but the caller can calculate it by looking at count.
- If the caller requests more than one channel, it will receive data for all channels starting with channels 0 to 3.
- If there is no data from the channels, the caller won’t receive any packet at all.
- In one-shot mode, it is recommended that you request one channel at a time.
- For more:
0bxxxxxxx1: More data is expected for this request in the next packet.
0bxxxxxxx0: All data is included in this packet.
0bxxxxxx1x: The system time has been updated since the last read.
STM_GET_COUNTER Description
The requester can request that the STM-Manager start sending counter values for a specific channel.
STM_GET_COUNTER Request Message Structure
struct stm_mgr_counter_req
{
int32_t mtype; /* stm-mgr-dst (160) */
int32_t mtype_src; /* caller's src mtype */
int32_t seq; /* caller's sequence number */
int32_t opcode; /* opcode = 21 */
uint32_t type_rsp; /* msg type that originates the request */
uint8_t mode; /* one shot or periodic mode */
uint32_t time; /* time interval in milliseconds */
int8_t channel; /* select Counter(s) to read */
};
In this example, you'll see the following:
- mode:
0: One shot
1: Periodic based on interval time
2: Disables the periodic mode - time: The time interval in milliseconds between each response (periodic mode) from STM-Manager
- channel: You can select which counter(s) to be read with this command. It is a bitmask as defined below:
0x01: Counter 1
0x02: Counter 2
0x80: Counter 8
0x03: Counters 1 and 2
STM_GET_COUNTER Response Message Structure
struct stm_mgr_counter_rsp
{
int32_t mtype; /* caller's dst mtype */
int32_t mtype_src; /* stm-mgr-src (161) */
int32_t seq; /* caller's sequence number */
int32_t opcode; /* opcode = 21 */
uint8_t count; /* Number of counters per packet. */
uint32_t time; /* Time of reading of counter in seconds */
uint32_t delta; /* Delta time in milliseconds since last reading */
uint8_t time_update; /* 0: no time update 1: System time got updated since last read */
Count_Data_t data[count]; /* counter data */
};
Struct Count_Data_t
{
uint8_t channel; /* Channel number */
uint32_t value; /* Counter value */
uint32_t diff; /* Number of counts in time interval */
STM_GET_HISTORY Description
The requester can request that the STM-Manager send the history of the inputs during the bootup time in the second resolution.
STM_GET_HISTORY Request Message Structure
struct stm_mgr_history_req
{
int32_t mtype; /* stm-mgr-dst (160) */
int32_t mtype_src; /* caller's src mtype */
int32_t seq; /* caller's sequence number */
int32_t opcode; /* opcode = 23 */
uint32_t type_rsp; /* msg type that originates the request */
};
STM_GET_HISTORY Response Message Structure
struct stm_mgr_hisory_rsp
{
int32_t mtype; /* caller's dst mtype */
int32_t mtype_src; /* stm-mgr-src (161) */
int32_t seq; /* caller's sequence number */
int32_t opcode; /* opcode = 23 */
uint8_t count; /* number of samples per packet */
uint8_t more; /* more data to come */
unit32_t history_data_t[count]; /* time stamp data in second resolution */
};
struct history_data_t
{
uint8_t input;
uint32_t time;
} __attribute__((__packed__)) history_data_t;
In this, you'll see these values:
- count: Indicates the number of transition changes in the specific channel during bootup. If there is no change, count will be zero.
- history_data_t[count]: The timestamp is in the second resolution based on RTC time.
- input: The state of the eight inputs captured on transition on any input.
- more:
1: More data is expected in the next packet.
0: All data is included in this packet.
STM_SET_DEBUG_MODE Description
The requester can enable and disable debug mode in the STM-Manager. You can provide the debug mask to enable debugging for a different part of the code.
STM_SET_DBG_MASK Message Structure
struct stm_mgr_set_dbg_mask_req
{
int32_t mtype; /* stm-mgr-dst (160) */
int32_t mtype_src; /* caller's src mtype */
int32_t seq; /* caller's sequence number */
int32_t opcode; /* opcode = 25 */
uint32_t dbg_mask; /* Debus mask defined below. 0 to disable debug */
};
Here is a debug mask:
#define DBG_GENERIC 0x0001
#define DBG_RCV 0x0002
#define DBG_TIMESTAMP 0x0004
#define DBG_TIMESTAMP_MORE 0x0008
#define DBG_COUNTER 0x0010
#define DBG_SYNC 0x0020
#define DBG_1BB 0x0040
#define DBG_HISTORY 0x0080
#define DBG_SCHEDULE 0x0100
#define DBG_OUTPUT 0x0200
#define DBG_CONFIG 0x0400
#define DBG_SND_REQ 0x0800
#define DBG_RCV_RSP 0x1000
#define DBG_PARSING 0x2000
#define DBG_INPUTS 0x4000
Set the uart Filter for Wake-up Using STM_WKP_FILTER
The requester can enable and disable filtering on the uart line for wake-up only.
STM_WKP_FILTER Request Message Structure
struct stm_mgr_wkp_filter
{
int32_t mtype; /* stm-mgr-dst (160) */
int32_t mtype_src; /* caller's src mtype */
int32_t seq; /* caller's sequence number */
int32_t opcode; /* opcode = 26 */
int32_t_ cmd; /* 1:Enabled 0:Disabled */
};
You need to enable this mode to avoid any unwanted wake-up from JPOD2 if the JPOD is a wake-up source.
For cmd:
- 0: STM8 will wake up at the first transition on the uart line and wake up IMX immediately.
<x>: STM8 wakes up on the first transition on the uart line and then checks the line every 25 seconds for X times, looking for a transition change. If there is no transition, it will go back to sleep.
STM_GET_INPUT Description
The requester can request that the STM-Manager start sending input states along with the timestamp captured at the time of the reading.
STM_GET_INPUT Request Message Structure
struct stm_mgr_get_input_req
{
int32_t mtype; /* stm-mgr-dst (160) */
int32_t mtype_src; /* caller's src mtype */
int32_t seq; /* caller's sequence number */
int32_t opcode; /* opcode = 27 */
uint32_t type_rsp; /* msg type that originates the request */
uint8_t mode; /* one shot or periodic mode */
uint32_t time; /* time interval in milliseconds */
int8_t mask; /* input mask */
};
In the preceding, you'll see the following:
- mode:
0: One shot
1: Periodic based on interval time
2: Disables the periodic mode - time: The time interval in milliseconds between each response (periodic mode) from the STM-Manager.
- mask: The input mask. You can select which inputs to monitor. If there is a change in the input, STM_Manager will send a response back to the caller.
STM_GET_INPUT Response Message Structure
struct stm_mgr_get_input_rsp
{
int32_t mtype; /* caller's dst mtype */
int32_t mtype_src; /* stm-mgr-src (161) */
int32_t seq; /* caller's sequence number */
int32_t opcode; /* opcode = 27 */
unsigned long long time; /* system time in ms */
uint8_t input; /* input state based on the input mask */
uint8_t time_update; /* 0: no system time update 1: system time was updated since last read */
};
Appendix A: Shared Memory Definitions
STM-Manager-SHM-State Definition (Unsigned 32 Bits )
#define STM_STATE_PWRUP (0) /* just got wakeup, powerup, reboot */
#define STM_STATE_INIT (1) /* initializing performing setup */
#define STM_STATE_RUN (2) /* monitoring coprocessor */
#define STM_STATE_SLEEP_PENDING (3) /* getting ready to sleep */
#define STM_STATE_SLEEP_DONE (4) /* sleep command issued to coprocessor */
STM-Manager Wake-up Source Definition
wakeup-sources
bit0 = ignition wakeup ( 0= disabled, 1= enabled, default setting = 1 )
bit1 = input_1 ( 0 = disabled, 1 = enabled , default setting = 1 )
bit2 = input_2 ( 0 = disabled, 1 = enabled , default setting = 1 )
bit3 = input_3 ( 0 = disabled, 1 = enabled , default setting = 1 )
bit4 = input_4 ( 0 = disabled, 1 = enabled , default setting = 1 )
bit5 = input_5 ( 0 = disabled, 1 = enabled , default setting = 1 )
bit6 = input_6 ( 0 = disabled, 1 = enabled , default setting = 1 )
bit7 = input_7 ( 0 = disabled, 1 = enabled , default setting = 1 )
bit8= reserved
bit09= Low battery detected
bit 10 = power state changes
bit 11 = radio ring signal
bit 12 = usb host controller-A signal
bit 13 = timer alarm interrupt
bit 14 = AUX1 uart_rx
bit 15 = motion interrupt signal
STM-Manager ADC Channels
STM_ADC_ADC_0 /* VIN */
STM_ADC_ADC_1 /* pin3 on 4pin power adaptor */
STM_ADC_ADC_2 /* pin 19 on 22 pin adaptor */
STM_ADC_ADC_3 /* pin 20 on 22 pin adaptor */
STM_ADC_ADC_4 /* pin 21 on 22 pin adaptor */
STM_ADC_ADC_5 /* pin 22 on 22 pin adaptor */
STM_ADC_BATTERY /* VCC BATTERY */
STM_ADC_GPS_ANTENNA /* GPS Antenna voltage */
Updated almost 3 years ago