Zephyr Project API 4.4.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
simcom-sim7080.h File Reference

Simcom SIM7080 modem public API header file. More...

#include <zephyr/types.h>
#include <stdbool.h>
#include <stdint.h>
#include <time.h>

Go to the source code of this file.

Data Structures

struct  sim7080_gnss_data
 Sim7080 gnss data structure. More...
struct  sim7080_sms
 Buffer structure for sms. More...
struct  sim7080_sms_buffer
 Buffer structure for sms reads. More...
struct  sim7080_ue_sys_info_gsm
 Sim7080 ue system information structure for gsm. More...
struct  sim7080_ue_sys_info_lte
 Sim7080 ue system information structure for LTE. More...
struct  sim7080_ue_sys_info
 Sim7080 ue system information structure. More...

Macros

#define SIM7080_GNSS_DATA_UTC_LEN   20
 Maximum Length of GNSS UTC data.
#define SIM7080_SMS_MAX_LEN   160
 Maximum SMS length.
#define SIM7080_UE_SYS_INFO_BAND_SIZE   32
 Maximum UE system information band size.
#define SIM7080_DNS_MAX_RECOUNT   10
 Maximum number of DNS retries.
#define SIM7080_DNS_MAX_TIMEOUT_MS   60000
 Maximum timeout for DNS queries in milliseconds.
#define SIM7080_LTE_CHANNEL_MASK_NB1   0x7BEFFU
 Channel Mask for NB-IoT.
#define SIM7080_LTE_CHANNEL_MASK_M1   0x5FFFFU
 Channel Mask for CAT-M1.
#define SIM7080_NUM_LTE_CHANNELS   19U
 Number of LTE channels supported by the modem.

Enumerations

enum  sim7080_state {
  SIM7080_STATE_INIT = 0 , SIM7080_STATE_IDLE , SIM7080_STATE_NETWORKING , SIM7080_STATE_GNSS ,
  SIM7080_STATE_OFF
}
 Sim7080 modem state. More...
enum  sim7080_rat { SIM7080_RAT_LTE_NB1 , SIM7080_RAT_LTE_M1 , SIM7080_RAT_LTE_AUTO , SIM7080_RAT_GSM }
 Modem radio access technology. More...
enum  sim7080_lte_chan {
  SIM7080_LTE_CHAN_B1 = BIT(0) , SIM7080_LTE_CHAN_B2 = BIT(1) , SIM7080_LTE_CHAN_B3 = BIT(2) , SIM7080_LTE_CHAN_B4 = BIT(3) ,
  SIM7080_LTE_CHAN_B5 = BIT(4) , SIM7080_LTE_CHAN_B8 = BIT(5) , SIM7080_LTE_CHAN_B12 = BIT(6) , SIM7080_LTE_CHAN_B13 = BIT(7) ,
  SIM7080_LTE_CHAN_B14 = BIT(8) , SIM7080_LTE_CHAN_B18 = BIT(9) , SIM7080_LTE_CHAN_B19 = BIT(10) , SIM7080_LTE_CHAN_B20 = BIT(11) ,
  SIM7080_LTE_CHAN_B25 = BIT(12) , SIM7080_LTE_CHAN_B26 = BIT(13) , SIM7080_LTE_CHAN_B27 = BIT(14) , SIM7080_LTE_CHAN_B28 = BIT(15) ,
  SIM7080_LTE_CHAN_B66 = BIT(16) , SIM7080_LTE_CHAN_B71 = BIT(17) , SIM7080_LTE_CHAN_B85 = BIT(18)
}
 Supported LTE channels. More...
enum  sim7080_sms_stat {
  SIM7080_SMS_STAT_REC_UNREAD = 0 , SIM7080_SMS_STAT_REC_READ , SIM7080_SMS_STAT_STO_UNSENT , SIM7080_SMS_STAT_STO_SENT ,
  SIM7080_SMS_STAT_ALL
}
 Possible sms states in memory. More...
enum  sim7080_ftp_rc { SIM7080_FTP_RC_OK = 0 , SIM7080_FTP_RC_FINISHED , SIM7080_FTP_RC_ERROR }
 Possible ftp return codes. More...
enum  sim7080_ue_sys_mode { SIM7080_UE_SYS_MODE_NO_SERVICE , SIM7080_UE_SYS_MODE_GSM , SIM7080_UE_SYS_MODE_LTE_CAT_M1 , SIM7080_UE_SYS_MODE_LTE_NB_IOT }
 UE system mode. More...
enum  sim7080_ue_op_mode {
  SIM7080_UE_OP_MODE_ONLINE , SIM7080_UE_OP_MODE_OFFLINE , SIM7080_UE_OP_MODE_FACTORY_TEST_MODE , SIM7080_UE_OP_MODE_RESET ,
  SIM7080_UE_OP_MODE_LOW_POWER_MODE
}
 UE operating mode. More...

Functions

enum sim7080_state mdm_sim7080_get_state (void)
 Get the current state of the modem.
int mdm_sim7080_power_on (void)
 Power on the Sim7080.
int mdm_sim7080_power_off (void)
 Power off the Sim7080.
void mdm_sim7080_force_reset (void)
 Forcefully reset the modem by pulling pwrkey for 15 seconds.
int mdm_sim7080_start_network (void)
 Activates the network operation mode of the modem.
int mdm_sim7080_stop_network (void)
 Stops the networking operation mode of the modem.
int mdm_sim7080_start_gnss (void)
 Starts the modem in gnss operation mode.
int mdm_sim7080_start_gnss_xtra (void)
 Starts the modem in gnss operation mode with xtra functionality.
int mdm_sim7080_stop_gnss (void)
 Stops the modem gnss operation mode.
int mdm_sim7080_download_xtra (uint8_t server_id, const char *f_name)
 Download the XTRA file for assisted gnss.
int mdm_sim7080_query_xtra_validity (int16_t *diff_h, int16_t *duration_h, struct tm *inject)
 Query the validity of the XTRA file.
int mdm_sim7080_query_gnss (struct sim7080_gnss_data *data)
 Query gnss position form the modem.
const char * mdm_sim7080_get_manufacturer (void)
 Get the sim7080 manufacturer.
const char * mdm_sim7080_get_model (void)
 Get the sim7080 model information.
const char * mdm_sim7080_get_revision (void)
 Get the sim7080 revision.
const char * mdm_sim7080_get_imei (void)
 Get the sim7080 imei number.
const char * mdm_sim7080_get_iccid (void)
 Get the sim7080 iccid number.
int mdm_sim7080_read_sms (struct sim7080_sms_buffer *buffer)
 Read sms from sim module.
int mdm_sim7080_delete_sms (uint16_t index)
 Delete a sms at a given index.
int mdm_sim7080_set_gpio (int gpio, int level)
 Set the level of one of the module's GPIO pins.
int mdm_sim7080_ftp_get_start (const char *server, const char *user, const char *passwd, const char *file, const char *path)
 Start a ftp get session.
int mdm_sim7080_ftp_get_read (char *dst, size_t *size)
 Read data from a ftp get session.
int mdm_sim7080_get_battery_charge (uint8_t *bcs, uint8_t *bcl, uint16_t *voltage)
 Read voltage, charge status and battery connection level.
int mdm_sim7080_get_ue_sys_info (struct sim7080_ue_sys_info *info)
 Read the ue system information.
int mdm_sim7080_get_local_time (struct tm *t)
 Get the local time of the modem.
int mdm_sim7080_dns_set_lookup_params (uint8_t recount, uint16_t timeout)
 Set the dns query lookup parameters.
void mdm_sim7080_dns_get_lookup_params (uint8_t *recount, uint16_t *timeout)
 Get the dns query lookup parameters.
void mdm_sim7080_get_rat (enum sim7080_rat *rat)
 Get the currently selected radio technology.
int mdm_sim7080_set_rat (enum sim7080_rat rat)
 Set the radio technology.
void mdm_sim7080_get_lte_bands (uint32_t *nb1, uint32_t *m1)
 Get the currently used LTE bands.
int mdm_sim7080_set_lte_bands (uint32_t nb1, uint32_t m1)
 Set the LTE bands to use.

Detailed Description

Simcom SIM7080 modem public API header file.

Copyright (C) 2021 metraTec GmbH

SPDX-License-Identifier: Apache-2.0

Macro Definition Documentation

◆ SIM7080_DNS_MAX_RECOUNT

#define SIM7080_DNS_MAX_RECOUNT   10

Maximum number of DNS retries.

◆ SIM7080_DNS_MAX_TIMEOUT_MS

#define SIM7080_DNS_MAX_TIMEOUT_MS   60000

Maximum timeout for DNS queries in milliseconds.

◆ SIM7080_GNSS_DATA_UTC_LEN

#define SIM7080_GNSS_DATA_UTC_LEN   20

Maximum Length of GNSS UTC data.

◆ SIM7080_LTE_CHANNEL_MASK_M1

#define SIM7080_LTE_CHANNEL_MASK_M1   0x5FFFFU

Channel Mask for CAT-M1.

◆ SIM7080_LTE_CHANNEL_MASK_NB1

#define SIM7080_LTE_CHANNEL_MASK_NB1   0x7BEFFU

Channel Mask for NB-IoT.

◆ SIM7080_NUM_LTE_CHANNELS

#define SIM7080_NUM_LTE_CHANNELS   19U

Number of LTE channels supported by the modem.

◆ SIM7080_SMS_MAX_LEN

#define SIM7080_SMS_MAX_LEN   160

Maximum SMS length.

◆ SIM7080_UE_SYS_INFO_BAND_SIZE

#define SIM7080_UE_SYS_INFO_BAND_SIZE   32

Maximum UE system information band size.

Enumeration Type Documentation

◆ sim7080_ftp_rc

Possible ftp return codes.

Enumerator
SIM7080_FTP_RC_OK 

Operation finished correctly.

SIM7080_FTP_RC_FINISHED 

Session finished.

SIM7080_FTP_RC_ERROR 

An error occurred.

◆ sim7080_lte_chan

Supported LTE channels.

Enumerator
SIM7080_LTE_CHAN_B1 

LTE Band 1.

SIM7080_LTE_CHAN_B2 

LTE Band 2.

SIM7080_LTE_CHAN_B3 

LTE Band 3.

SIM7080_LTE_CHAN_B4 

LTE Band 4.

SIM7080_LTE_CHAN_B5 

LTE Band 5.

SIM7080_LTE_CHAN_B8 

LTE Band 8.

SIM7080_LTE_CHAN_B12 

LTE Band 12.

SIM7080_LTE_CHAN_B13 

LTE Band 13.

SIM7080_LTE_CHAN_B14 

LTE Band 14.

SIM7080_LTE_CHAN_B18 

LTE Band 18.

SIM7080_LTE_CHAN_B19 

LTE Band 19.

SIM7080_LTE_CHAN_B20 

LTE Band 20.

SIM7080_LTE_CHAN_B25 

LTE Band 25.

SIM7080_LTE_CHAN_B26 

LTE Band 26.

SIM7080_LTE_CHAN_B27 

LTE Band 27.

SIM7080_LTE_CHAN_B28 

LTE Band 28.

SIM7080_LTE_CHAN_B66 

LTE Band 66.

SIM7080_LTE_CHAN_B71 

LTE Band 71.

SIM7080_LTE_CHAN_B85 

LTE Band 85.

◆ sim7080_rat

Modem radio access technology.

Enumerator
SIM7080_RAT_LTE_NB1 

NB-IoT only.

SIM7080_RAT_LTE_M1 

LTE CAT M1 only.

SIM7080_RAT_LTE_AUTO 

Modem automatically selects M1 or NB1.

SIM7080_RAT_GSM 

GSM.

◆ sim7080_sms_stat

Possible sms states in memory.

Enumerator
SIM7080_SMS_STAT_REC_UNREAD 

Message unread.

SIM7080_SMS_STAT_REC_READ 

Message read.

SIM7080_SMS_STAT_STO_UNSENT 

Message stored unsent.

SIM7080_SMS_STAT_STO_SENT 

Message stored sent.

SIM7080_SMS_STAT_ALL 

Status count.

◆ sim7080_state

Sim7080 modem state.

Enumerator
SIM7080_STATE_INIT 

Initial modem state.

SIM7080_STATE_IDLE 

Modem idle.

SIM7080_STATE_NETWORKING 

Network active.

SIM7080_STATE_GNSS 

GNSS active.

SIM7080_STATE_OFF 

Modem off.

◆ sim7080_ue_op_mode

UE operating mode.

Enumerator
SIM7080_UE_OP_MODE_ONLINE 

Online.

SIM7080_UE_OP_MODE_OFFLINE 

Offline.

SIM7080_UE_OP_MODE_FACTORY_TEST_MODE 

Factory test mode.

SIM7080_UE_OP_MODE_RESET 

Reset.

SIM7080_UE_OP_MODE_LOW_POWER_MODE 

Low power mode.

◆ sim7080_ue_sys_mode

UE system mode.

Enumerator
SIM7080_UE_SYS_MODE_NO_SERVICE 

No service.

SIM7080_UE_SYS_MODE_GSM 

GSM.

SIM7080_UE_SYS_MODE_LTE_CAT_M1 

LTE CAT M1.

SIM7080_UE_SYS_MODE_LTE_NB_IOT 

LTE NB IOT.

Function Documentation

◆ mdm_sim7080_delete_sms()

int mdm_sim7080_delete_sms ( uint16_t index)

Delete a sms at a given index.

Parameters
indexThe index of the sms in memory.
Returns
0 on success. Otherwise -1 is returned.

◆ mdm_sim7080_dns_get_lookup_params()

void mdm_sim7080_dns_get_lookup_params ( uint8_t * recount,
uint16_t * timeout )

Get the dns query lookup parameters.

Parameters
recount[out] Number of retries per query.
timeout[out] Timeout for a dns query in milliseconds.

◆ mdm_sim7080_dns_set_lookup_params()

int mdm_sim7080_dns_set_lookup_params ( uint8_t recount,
uint16_t timeout )

Set the dns query lookup parameters.

Parameters
recountNumber of retries per query. Maximum SIM7080_DNS_MAX_RECOUNT
timeoutTimeout for a dns query in milliseconds. Maximum SIM7080_DNS_MAX_TIMEOUT_MS
Returns
0 on success. Otherwise a negative error is returned.

◆ mdm_sim7080_download_xtra()

int mdm_sim7080_download_xtra ( uint8_t server_id,
const char * f_name )

Download the XTRA file for assisted gnss.

Parameters
server_idId of the server to download XTRA file from.
f_nameThe name of the XTRA file to download.
Returns
0 on success. Otherwise <0 is returned.

◆ mdm_sim7080_force_reset()

void mdm_sim7080_force_reset ( void )

Forcefully reset the modem by pulling pwrkey for 15 seconds.

Note
The state of the modem may be undefined after calling this function. Call mdm_sim7080_power_on after force reset.

◆ mdm_sim7080_ftp_get_read()

int mdm_sim7080_ftp_get_read ( char * dst,
size_t * size )

Read data from a ftp get session.

Parameters
dstThe destination buffer.
sizeInitialize to the size of dst. Gets set to the number of bytes actually read.
Returns
According sim7080_ftp_rc.

◆ mdm_sim7080_ftp_get_start()

int mdm_sim7080_ftp_get_start ( const char * server,
const char * user,
const char * passwd,
const char * file,
const char * path )

Start a ftp get session.

Parameters
serverThe ftp servers address.
userUser name for the ftp server.
passwdPassword for the ftp user.
fileFile to be downloaded.
pathPath to the file on the server.
Returns
0 if the session was started. Otherwise -1 is returned.

◆ mdm_sim7080_get_battery_charge()

int mdm_sim7080_get_battery_charge ( uint8_t * bcs,
uint8_t * bcl,
uint16_t * voltage )

Read voltage, charge status and battery connection level.

Parameters
bcs[out] Charge status.
bcl[out] Battery connection level.
voltage[out] Battery voltage in mV.
Returns
0 on success. Otherwise a negative error is returned.

◆ mdm_sim7080_get_iccid()

const char * mdm_sim7080_get_iccid ( void )

Get the sim7080 iccid number.

◆ mdm_sim7080_get_imei()

const char * mdm_sim7080_get_imei ( void )

Get the sim7080 imei number.

◆ mdm_sim7080_get_local_time()

int mdm_sim7080_get_local_time ( struct tm * t)

Get the local time of the modem.

Parameters
tTime structure to fill.
Returns
0 on success. Otherwise a negative error is returned.
Note
Time is set by network. It may take some time for it to get valid.

◆ mdm_sim7080_get_lte_bands()

void mdm_sim7080_get_lte_bands ( uint32_t * nb1,
uint32_t * m1 )

Get the currently used LTE bands.

Parameters
nb1[out] Used NB-IoT bands. May be NULL.
m1[out] Used CAT-M1 bands. May be NULL.

◆ mdm_sim7080_get_manufacturer()

const char * mdm_sim7080_get_manufacturer ( void )

Get the sim7080 manufacturer.

◆ mdm_sim7080_get_model()

const char * mdm_sim7080_get_model ( void )

Get the sim7080 model information.

◆ mdm_sim7080_get_rat()

void mdm_sim7080_get_rat ( enum sim7080_rat * rat)

Get the currently selected radio technology.

Parameters
rat[out] Gets set to the current technology.

◆ mdm_sim7080_get_revision()

const char * mdm_sim7080_get_revision ( void )

Get the sim7080 revision.

◆ mdm_sim7080_get_state()

enum sim7080_state mdm_sim7080_get_state ( void )

Get the current state of the modem.

Returns
The current state.

◆ mdm_sim7080_get_ue_sys_info()

int mdm_sim7080_get_ue_sys_info ( struct sim7080_ue_sys_info * info)

Read the ue system information.

Parameters
infoDestination buffer for information.
Returns
0 on success. Otherwise a negative error is returned.

◆ mdm_sim7080_power_off()

int mdm_sim7080_power_off ( void )

Power off the Sim7080.

Returns
0 on success. Otherwise -1 is returned.

◆ mdm_sim7080_power_on()

int mdm_sim7080_power_on ( void )

Power on the Sim7080.

Returns
0 on success. Otherwise -1 is returned.

◆ mdm_sim7080_query_gnss()

int mdm_sim7080_query_gnss ( struct sim7080_gnss_data * data)

Query gnss position form the modem.

Returns
0 on success. If no fix is acquired yet -EAGAIN is returned. Otherwise <0 is returned.

◆ mdm_sim7080_query_xtra_validity()

int mdm_sim7080_query_xtra_validity ( int16_t * diff_h,
int16_t * duration_h,
struct tm * inject )

Query the validity of the XTRA file.

Parameters
diff_hDifference between the local time and the XTRA inject time in hours.
duration_hValid time of the XTRA file in hours.
injectInjection time of the XTRA file.

◆ mdm_sim7080_read_sms()

int mdm_sim7080_read_sms ( struct sim7080_sms_buffer * buffer)

Read sms from sim module.

Parameters
bufferBuffer structure for sms.
Returns
Number of sms read on success. Otherwise -1 is returned.
Note
The buffer structure needs to be initialized to the size of the sms buffer. When this function finishes successful, nsms will be set to the number of sms read. If the whole structure is filled a subsequent read may be needed.

◆ mdm_sim7080_set_gpio()

int mdm_sim7080_set_gpio ( int gpio,
int level )

Set the level of one of the module's GPIO pins.

Parameters
gpioGPIO pin number
levelNew logical level of the GPIO
Returns
0 on success. Otherwise -1 is returned.
Note
The GPIO will be configured as output implicitly.

◆ mdm_sim7080_set_lte_bands()

int mdm_sim7080_set_lte_bands ( uint32_t nb1,
uint32_t m1 )

Set the LTE bands to use.

Parameters
nb1NB-IoT bands to use. 0 to not change the bands.
m1CAT-M1 bands to use. 0 to not change the bands.
Return values
0Success.
-EINVALThe band selection is illegal.
Note
This function needs to be called before mdm_sim7080_start_network(). If networking is already active, the change will not affect the current session. To apply changes, networking has to be restarted. A power cycle may be needed for the modem to forget the last working configuration.
Available NB-IoT and CAT-M1 differ. Refer to SIM7080_LTE_CHANNEL_MASK_NB1 and SIM7080_LTE_CHANNEL_MASK_M1.

◆ mdm_sim7080_set_rat()

int mdm_sim7080_set_rat ( enum sim7080_rat rat)

Set the radio technology.

Parameters
ratThe radio technology.
Return values
0Success.
-EINVALThe selected technology is not available.
Note
This function needs to be called before mdm_sim7080_start_network(). If networking is already active, the change will not affect the current session. To apply changes, networking has to be restarted. A power cycle may be needed for the modem to forget the last working configuration.

◆ mdm_sim7080_start_gnss()

int mdm_sim7080_start_gnss ( void )

Starts the modem in gnss operation mode.

Returns
0 on success. Otherwise <0 is returned.
Note
The modem needs to be booted for this function to work. Concurrent use of network and gnss is not possible.

◆ mdm_sim7080_start_gnss_xtra()

int mdm_sim7080_start_gnss_xtra ( void )

Starts the modem in gnss operation mode with xtra functionality.

Returns
0 on success. Otherwise <0 is returned.
Note
The modem needs to be booted for this function to work. Concurrent use of network and gnss is not possible.
If enabling xtra functionality fails a normal cold start will be performed.
Warning
On some modem firmware revisions (e.g. 1951B16SIM7080) power cycling the gnss functionality with an xtra file can cause a hangup of the modem. This can be triggered by calling mdm_sim7080_start_gnss_xtra(), then turning off gnss by calling mdm_sim7080_stop_gnss() and then re-enabling gnss by calling mdm_sim7080_start_gnss_xtra() again. In this case the modem will not respond to commands anymore and every call of a modem function will result in a timeout. In this case the whole modem needs to be power cycled by calling mdm_sim7080_power_off() and mdm_sim7080_power_on(). It is advised to power cycle the modem before using the gnss functionality to avoid hangups.

◆ mdm_sim7080_start_network()

int mdm_sim7080_start_network ( void )

Activates the network operation mode of the modem.

Returns
0 on success. Otherwise <0 is returned.
Note
The modem needs to be booted for this function to work. Concurrent use of network and gnss is not possible.

◆ mdm_sim7080_stop_gnss()

int mdm_sim7080_stop_gnss ( void )

Stops the modem gnss operation mode.

Returns
0 on success. Otherwise <0 is returned.

◆ mdm_sim7080_stop_network()

int mdm_sim7080_stop_network ( void )

Stops the networking operation mode of the modem.

Returns
0 on success. Otherwise <0 is returned.