TiLDA MK4/sim800

Overview

The TiLDA MK4 is equipped with an SIM800C module. This is primarily a GSM module for communication with a mobile network. It also has many other features including Bluetooth, a file system and some audio features.

Below are the features and functions exposed thought this library.

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()

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.

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

Power and Status

sim800.btpoweron()

Turn on Bluetooth. You may also want to call sim800.btvisible(True) to make your badge discoverable.

sim800.btpoweroff()

Turn of Bluetooth.

sim800.btison()

Returns True if Bluetooth is turned on.

sim800.btstatus()

This returns the status of the Bluetooth stack:

0 = Initial (Not powered on)

1 = Disactivating

2 = Activating

5 = Idle (Normal and waiting)

6 = Inquiry

7 = Inquiry Res Ind

8 = Cancelling inquiry

9 = Bonding

11 = Pairing

12 = Connecting

14 = Deleting paired device

15 = Deleting all paired device

19 = Pairing confirm while passive pairing

sim800.btrssi(device)

• device: The device to check. This can be obtained using sim800.btpaired().

Returns the signal quality for the device (-127-0)

Settings

sim800.btname([name])

Get and Set the Bluetooth name for your badge.

• name: The new name of your badge. Omit this to just read the current setting.

Returns the name (possubly the new name) of the badge.

sim800.btaddress()

Returns the Bluetooth address of the badge.

Pairing

Before you can use other devices over Bluetooth or they can use you you will first need to pair the device.

You can pair to most devices. This includes hands free kits for making calls thought your badge.

sim800.btvisible([visible])

• visible: If True the badge is visible to other Bluetooth devices.

sim800.btscan([timeout])

Scan for other Bluetooth devices.

• Timeout: Time in milliseconds to search. 10000 to 60000 in increments of 10000. Defaults to 30000.

Returns a list of device IDs, Names, address, and the rssi of the discovered devices.

sim800.btpair(device)

Request a pairing with another device.

• device: The ID of the device returned from sim800.btscan().

You will then need to confirm the pairing with sim800.btpairconfirm().

sim800.btpairconfirm([passkey])

This should only be called once the user has confirmed that the value of sim800.btparingpasscode() is the same number as displayed on the other device.

• passkey: If your pairing needs a passkey to be entered. This is an old 4 figure pin for compatibility should not be confused with the 6 figure code shown on the other device.

You can monitor for incoming pairing requests using the callbacks documented below.

sim800.btpairreject()

Reject an incoming paring request.

sim800.btparingname()

Returns the name of the device trying to pair with you.

sim800.btparingpasscode()

Returns the passcode that the user should check against the screen on the other device.

sim800.btunpair([device])

Unpair a Bluetooth device.

• device: The ID of the device to unpair. This can be found by calling sim800.btpaired(). 0 to unpair everything.

sim800.btpaired()

Returns a list of paired devices.

Connecting

Once a device is paired you can connect them using a profile to do something useful. please check the SIM800 documentation listed at the bottom to check what is supported by the SIM800C on the MK4 badge.

sim800.btgetprofiles(device)

• device: The device to check. This can be obtained using sim800.btpaired().

Returns a list of supported profiles a paired device supports.

sim800.btprofilesupported(device, profile)

Check if a specific profile is supported by a device.

• device: The device to check. This can be obtained using sim800.btpaired().
• profile: The name (string) or ID (integer) of the profile.

Returns True if it is supported.

sim800.btconnect(device, profile)

• device: The device to connect. This can be obtained using sim800.btpaired().
• profile: The ID (integer) of the profile to connect.

sim800.btdisconnect(device)

• device: The profile dosconnect. This can be obtained using sim800.btconnected().

sim800.btconnected()

Returns a list of connected profiles.

Object Push Profile (OPP)

This is used to transfer files over Bluetooth. This will transfer files between the internal storage that is limited to about 90K) and other devices. See the File System section for how to transfer data to and from the file system.

sim800.btopppush(device, filename)

Send a file to another device.

• device: The device ID. This can found using sim800.btpaired().
• filename: The full filename (including directory) if the file to send.

sim800.btoppaccept()

Accept an incoming file from a paired device.

You can get notification of an incoming connection by monitoring "+BTOPPPUSHING:" using the callbacks feature. Files stored in "\\User\\BtReceived".

sim800.btoppreject()

Reject a file being offered by another device.

Serial Port Profile (SPP)

This allows serial communication with a paired device. At the time of writing this has been written to specification and has not been tested. We hope to have this tested in time but please report any issues to @alistair.

sim800.btsppwrite(connection, data)

• connection: The ID of the connected device.
• data: The data to send.

sim800.btsppread(connection)

• connection: The ID of the connected device.

Any received data is returned as a string.

Bluetooth Calling

These allow use of phones features over Bluetooth.

sim800.btcall(number)

• number: The number to call

sim800.btanswer()

Answer an incoming call.

sim800.bthangup()

End or reject a call

sim800.btredial()

Redial the last number

sim800.btdtmf(number)

Send DTMF tones.

• number: The number to send.

sim800.btvoicevolume([gain])

• gain: The volume of the speaker (0-15). Will remain unchanged if omitted.

Returns the volume if changed or not.

sim800.btvoicevolume([gain])

• gain: The gain of the microphone (0-15). Will remain unchanged if omitted.

Returns the gain if changed or not.

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.

Record Audio

sim800.startrecording([id],[length])

• id: The ID of the recording (1-10). Defaults to 1.
• length: The maximum duration of the audio to record in ms. No limit if not set.

sim800.stoprecording()

Stop recording audio.

Playback recordings

sim800.startplayback([id], [channel], [level], [repeat])

• id: The ID of the recording (1-10). Defaults to 1.
• channel: The device to play back on. 0 is the speaker.
• level: Volume to play back at as a percentage.
• repeat: If True the audio will loop.

sim800.stopplayback()

1. Stop playback

Stop playing back audio.

Manage Recordings

Although the recordings show up in the file system you will need to use these functions to manage them.

sim800.listrecordings()

Returns an array of the stored recordings.

sim800.deleterecording([id])

• id: The ID of the recording (1-10). Defaults to 1.

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.getstatus()

Gets the status of the SIM800.

Returns:

0 = Ready

2 = Unknown:

3 = Ringing

4 = Call in progress

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.ussd(ussdstring, [timeout])

Request Unstructured Supplementary Service Data from network (*#xxxxxx#)

• ussdstring: The command. "*#100#" for example
• timeout: Time to wait in milliseconds.

sim800.getmynumber()

Get the telephone number from the network. This only works with some networks.

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.

Network selection

sim800.listoperators([available_only])

• available_only: If True (default) only the networks you can connect to are listed.

A list of arrays is returned with the following parameters.

1=available,2=current,3=forbidden

Long name

Short name

GSMLAI

sim800.currentoperator(format)

• format: The format to return the data in. 0=Long name, 1=Short name, 2=GSMLAI

Returns the current operator.

sim800.setoperator(mode, [format], [operator]

This can be used to change the operator. It can also make +COPS calls to the SIM800.

• mode: 0=automatic,1=Manual selection,2=deregister only,4=try manual then automatic if fails])
• format: Format of the operator parameter. 0=Long name, 1=Short name, 2=GSMLAI
• operator: The operator to use.

If you mess things up then sim800.setoperator(0) will reset to defaults. sim800.setoperator(1,3,"23404") will force you on to the EMF Camp network.

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()

Firmware

sim800.getfirmwarever()

Returns the firmware version installed on the SIM800. If it does not end with "_BT" then your Bluetooth will not work. Drop in to the badge tent or contact the badge team online for help.