TiLDA MK4/sim800

Settings

Ringer Volume

sim800.ringervolume([level])

level: If set the volume as a percentage is changed to that value. If not set the volume will not change.

The current (possibly new) volume level is returned.

Speaker Volume

sim800.speakervolume(level)

level: If set the volume as a percentage is changed to that value. If not set the volume will not change.

The current (possibly new) volume level is returned.

Ringtone

The SIM800 has 19 terrible ringtones. You can select any of them. My federate is 0 that is also silent.

sim800.ringtone([alert],[preview])

alert: The number of the new ringtone (0-19). preview: If True it will play. If False or absent then it will stop.

The current (possible new) ringtone is returned. The ringtone is always changed regardless of the preview setting.

Calling

Call

sim800.call(number)

number = Number to call. This can be an integer but you will need ti use a string if your number has a "0" prefix

Answer Call

sim800.answer()

End/Reject Call

sim800.hangup()

Redial

sim800.redial()

Ringing

sim800.isringing()

Returns True if ringing.

The sim800.getstatus() also returns 2 when ringing and machine.Pin(machine.Pin.GPIO_SIM_RI, machine.Pin.IN).value() will show the start of the hardware ringer indicator pin. You an also user a callback (documented below) with the call name of "RING".

sim800.latestnumber()

Returns the number of the current caller if ringing. Returns the number of the last caller if not ringing.

Play DTMF

sim800.dtmf(number)

Plays DTMF tones on an active call.

number: The number of the tone to play. This can a string of numbers that are played in sequence. Using "," will pause for one second. (int or str)

SMS

List SMS Messages

sim800.listsms([stat])

List available SMS messages.

stat:

0 = received unread messages (default)

1 = Received read messages

2 = Stored unsent messages

3 = Stored sent messages

4 = All message

sim800.newsms()

Returns True if you have a new (unread) SMS message

Read an SMS Message

sim800.readsms(index, leaveunread)

index: The index of the message to read. This can be found by calling sim800.listsms(). leaveunread: If set to True the message will remain flagged as unread if it was to start with. If False (default) then it will be marked as read.

If you are looking for a message to process consider setting leaveunread to True until you identify the message is for you or the user will continually find all there messages are read.

The contents of the message is returned as a string.

Send an SMS Message

sim800.sendsms(number, message)

number: The number to send the SMS message to. message: The message to send as a string. This must be less than 160 8-bit charicters in length.

Delete an SMS Message

sim800.deletesms(index)

index: The index of the message to delete. This can be found by calling sim800.listsms().

File System

The SIM800 module has around 90KB of file storage. This can be used to store files to send to or receive from and paired Bluetooth device as well as for audio recordings.

Free Space

sim800.fsfree()

Returns the number of bytes available in the file system.

List Directory

sim800.fsls([directory])

directory: The directory on the file system relative to root to list. Directories end with a backslash. The root directory is returned if no parameter is given.

A list of file names is returned. Directories end with a "\". Don't forget to escape this as "\\" in your code.

File Size

sim800.fssize(filename)

filename: The directory and filename of the file.

The size of the file in bytes. A size of -1 is returned if the file does not exist.

Create Directory

sim800.fsmkdir(directory)

Creates a directory.

directory: The name of the directory to create.

Remove Directory

Removes a directory.

sim800.fsrmdir(directory)

directory: The name of the directory to delete.

Create a file

sim800.fscreate(filename)

Creates an empty file.

filename: The filename of the file (including directory) to create.

Read From File

sim800.fsread(filename)

Returns the contents of the file.

filename: The filename of the file (including directory) to read.

Note that this can be slow. You may want to use sim800.uartspeed(460800) to speed things up but you are advised to call sim800.uartspeed(0) after to switch back to automatic.

Write To File

sim800.fswrite(filename, data, [truncate])

filename: The filename of the file (including directory) to read. data: The data to write to the file truncate: If True the original file emptied first. If False data is appended to the end of the file. Defaults to False.

Note that this can be slow. You may want to use sim800.uartspeed(460800) to speed things up but you are advised to call sim800.uartspeed(0) after to switch back to automatic.

Delete File

sim800.fsrm(filename)

filename: The filename of the file to delete.

Rename File

sim800.fsmv(from, to)

Rename a file.

from: The old filename. To: The new filename.

Bluetooth

sim800.

Audio

Play Tone

sim800.playtone([freq],[duration],[async])

freq: The frequency to play in Hz. duration: The duration of the tone in milliseconds. async: If True (dafault) it will return instantly and the audio will continue to play for the duration.

System, Network and Status

Power

The SIM800 module will be powered up when the library is first loaded. You can turn it on and off if you want.

sim800.ison()

Returns true if the SIM800 is powered up.

sim800.poweron([async])

async: If True it will return immediately and power on in the background. If False (default) it will wait until it has booted before returning.

True is returned of the SIM800 if turned on.

sim800.poweroff([async])

async: If True it will return immediately and power on in the background. If False (default) it will wait until it has powered off before returning.

True is returned of the SIM800 if turned off.

Battery

sim800.batterycharging()

Returns true of the battery is charging.

sim800.batterycharge()

Returns the percentage charge of the battery.

Network and SIM Information

sim800.imei()

Return the IMEI (International Mobile Equipment Identity) of the badge.

sim800.imsi()

Return the IMSI (International mobile subscriber identity) of the SIM.

sim800.iccid()

Returns the SIM card's unique serial number.

sim800.rssi()

Return the Received Signal Strength Indication (signal strength) of the current cell communication.

• 0: -115 dBm
• 1: -111 dBm
• 2...30: -110...-54 dBm
• 31:: -52 dBm
• >99: No signal

sim800.ber()

Returns the Bit Error Rate (signal quality) of the current cell communication. Percent value.

sim800.cellid()

Returns the Cell ID of the currently connected cell tower.

sim800.engineeringinfo([neighbour])

neighbour: Include full neighbouring cell information if True.

Returns the engineering information (documented in the docuemtns listed in the advanced section) for the current cell and 6 neighbouring cells.

Callbacks

Register for a Callback

sim800.call(call, function)

You can register a function that is called when a response is sent by the SIM800. This allows you to detect calls, incoming messages, Bluetooth requests and other advanced responses.

call: The response call to be watched for function: The function to be called.

The function must take one string parameter. This parameter contains the the parameters sent from the SIM800. You pass the function by it's name without the training brackets.

Some example calls are;

• "RING" - Triggered when an incoming call is detected.
• "+CLIP:" - When caller line identification is received (ie the caller's number).
• "+CMT:" - A new SMS message is received.
• "+DTMF:" - A DTMF tone is detected.
• "+BTPAIRING:" - A Bluetooth paring request.

For "RING" the parameter will always be an empty string but your function must accept it. When this is triggered the library the callers number may not be valid and "+CLIP:" should be used instead.

Take care not to change things the active app will be using such as the string. This call will be in the same thread but may happen in the middle of another function. If odd things start happening with anything on the badge then try disabling your callbacks is a good thing to try.

Deregister from a Callback

sim800.deregistercallback(function)

function: The function that was used when registering for the callback.

Advanced

UART Speed

The communication with the SIM800 autosuggestion by default and we default to 115200 for speed and reliability. You can set the speed to other bauds with the following command.

sim800.uartspeed(newbaud)

newbaud: The speed of the internal communication. Valid values are 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200, 230400 and 460800. 0 To revert to default.

If the badge is rebooted but not power cycled then the speed can get out of sync. Consider switching back to auto when you can to prevent issues related to this.

Custom SIM800 Command Calls

sim800.command([command], [response_timeout], [required_response], [custom_endofdata])

command: The AT command to send. A full set of of these commands are available in the SIMCom documentation. Links to the most useful ones are below. response_timeout: The time to wait for a response in milliseconds. required_response: The start of a response we will keep waiting for. If not found in time we will receive a "TIMEOUT" custom_endofdata: The start of a response we want for data sent after an "OK" or "ERROR" response.

This returns an array that should start with an echo of the command sent and normally ends with a response identifying if the call was successful. If a required_response or custom_endofdata is specified then this will be the last line. If such a response has not been received before the timeout a response of "TIMEOUT" is sent.

As other apps may be monitoring the SIM800 for data relevant to them. Please do not access the UART directly unless you really have to. If you want to receive then use the callback above and call sim800.processbuffer() to process the incoming data. If you really have to then you can access the UART directly via sim800.uart.

Further details about the AT commands can be found in the following documents.

• SIM800 Series AT Command Manual
• SIM800 Series Bluetooth Application Note
• SIM800 Series FS Application Note

Helper Functions

There are also some helper functions that you might find useful.

sim800.sim800.ispositive(response)

response: The last line of data returned from sim800.command().

Returns True if it was positive such as "OK" or "CONNECTED".

sim800.isnegative(response)

response: The last line of data returned from sim800.command().

Returns True if it was negative such as "ERROR" or "NO CARRIER".

sim800.extractval(parameter, response, [default])

This looks for the first occurrence of a parameter passed back from the SIM800.

The value of the parameter is returned as a string, or the default if it is not found.

parameter: The parameter you are looking for. "+GCAP:" for example. response: The response from sim800.command() default: The value to return if the parameter is not found. Defaults to an empty string.

sim800.extractvals(parameter, response)

This looks for the occurrences of a parameter passed back from the SIM800.

An array of values of the parameters are returned.

parameter: The parameter you are looking for. "+CENG:" for example. response: The response from sim800.command()